Aperçu

BarTender 2022 introduit une API RESTful qui vous permet d'automatiser les travaux d'impression via des appels REST. Les API REST sont la méthode moderne permettant aux applications et systèmes d'échanger des données entre eux sur un réseau ou Internet. Les requêtes exécutent des fonctions sur la ressource du serveur, ce qui peut modifier son état/forme/statut, mais aussi effectuer des actions côté serveur associées. Si vous avez déjà utilisé l'API REST de Print Portal ou toute autre API REST, ce style d'appels API vous semblera assez familier. Cependant, contrairement aux API mentionnées précédemment, le fonctionnement de ces appels API ressemble davantage aux actions d'Integration ou de Process Builder.

S'applique à

BarTender 2022 et versions ultérieures

Édition Automation ou supérieure

Informations

Prérequis pour l'API REST

• Version : BarTender 2022 R1 et versions ultérieures
• Édition : Automation ou Enterprise
• Application d'envoi : Personnalisée, Swagger, Insomnia, Postman
  • Prend en charge IWA, NTLM et l'authentification basique
  • Prend en charge CORS
  • Curl, C# et les langages .NET sont pris en charge pour les applications personnalisées
• BarTender doit être installé pour recevoir les commandes

L'API fonctionne sur le port 5159, donc ce port doit être ouvert pour que l'API puisse recevoir les commandes REST.

Sécurité

L'API REST prend en charge plusieurs types d'authentification

• Authentification basique
• Authentification Windows intégrée (IWA)
• Challenge/Réponse Windows (NTLM)

Par défaut, l'authentification basique est désactivée.

Lorsque vous utilisez Insomnia ou Postman pour envoyer des requêtes, définissez l'authentification sur NTLM.

Lorsque vous utilisez IWA, le compte qui envoie les requêtes REST doit avoir les propriétés suivantes :

• L'utilisateur qui envoie la requête doit avoir l'autorisation de se connecter au serveur
• L'utilisateur doit avoir les droits d'administration des intégrations définis dans la Console d'administration

Utilisation de l'authentification basique

L'authentification basique est désactivée par défaut. Pour l'activer, veuillez suivre les étapes suivantes :

1. Accédez à C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 si vous utilisez la dernière version).
2. Trouvez le fichier appsettings.json.
3. Descendez jusqu'à AuthenticationSchemes vers le bas du fichier et changez Basic de false à true (en minuscules).
4. Enregistrez le fichier.
5. Ouvrez la Console d'administration.
6. Allez dans Services Windows dans le menu à gauche et redémarrez le Service d'intégration BarTender.

Utilisation via HTTPS

L'API REST repose sur le serveur HTTP de Windows (Http.sys). Cependant, vous pouvez configurer l'API REST pour utiliser HTTPS afin de sécuriser vos connexions.

Comme pour la configuration HTTPS avec les intégrations, les requêtes REST passeront par Print Portal. Vous aurez besoin d'un certificat SSL, soit délivré par une autorité de certification, soit auto-signé pour ce processus.

1. Commencez par sécuriser Print Portal avec HTTPS en utilisant votre certificat SSL.
2. Redirigez tous les appels RESTful vers https://localhost/Bartender/api/actions. Remplacez localhost par le nom du serveur ou l'adresse IP si nécessaire.

Commandes de l'API REST

L'API REST de BarTender utilise seulement trois commandes REST : POST, GET et PATCH. Voici un aperçu de la façon dont chacune interagit avec l'API.

Les IDs sont utilisés pour travailler avec toute action actuellement déployée. Lorsque vous envoyez un script via POST, l'ID est inclus dans la réponse si le script a été accepté par l'API. L'ID reste valide tant que le script est actif sur le serveur API. Par défaut, c'est 60 minutes, mais cela peut être modifié dans le message POST.

Les variables que vous pouvez récupérer avec un GET fonctionnent comme les variables dans une intégration. Vous pouvez récupérer des variables d'intégration et globales ainsi que toutes les variables locales que vous créez via des actions POST. Les valeurs récupérées seront relatives à l'ID du script soumis.

Scripts POST

Lorsque vous utilisez une commande POST, vous pouvez demander à BarTender d'effectuer différentes actions et de laisser ces actions actives après l'envoi. Par défaut, une action restera active pendant 60 minutes, mais ce délai est modifiable.

POST permet de demander à BarTender d'effectuer diverses actions. Si vous avez déjà utilisé Integration Builder ou Process Builder, ces catégories devraient vous sembler familières car ce sont les mêmes types de commandes utilisées par ces applications. Voici la liste des catégories :

• Actions d'impression - Imprimer un document, Script de commande, Script BTXML
• Actions d'entrée - Lire un fichier, écouter un port série, etc.
• Actions de sortie – Écrire un message dans le journal, envoyer une requête Web Service, etc.
• Actions d'exécution – Définir une variable, exécuter une commande shell, etc.
• Actions sur les fichiers - Créer un dossier, copier un fichier, supprimer un fichier, etc.
• Actions de transformation – Action de recherche et remplacement, recherche et suppression, etc.
• Actions sur la base de données - Exécuter du SQL, transformer du texte en ensemble d'enregistrements, pour chaque enregistrement de la base de données, etc. (voir la section Base de données ci-dessous)

Lors de l'envoi d'un POST, ces actions peuvent être écrites en script BTXML, YAML ou JSON. Si vous avez déjà une intégration BTXML fonctionnelle, utiliser BTXML peut être la transition la plus rapide pour vous. Voici un exemple de script d'impression BTXML :

Si vous avez déjà travaillé avec des API REST, que vous créez une nouvelle interface API ou que vous êtes simplement plus à l'aise avec JSON ou YAML, l'API accepte également ces formats. Ils sont un peu plus simples et plus lisibles que le BTXML. Voici quelques exemples dans les deux formats :

Après avoir soumis le POST, l'API renverra une réponse. Cette réponse contiendra un code d'état qui vous indiquera si le script a été accepté ou non. Vous devez rechercher le code 201, qui indique que le script a été accepté et est programmé pour s'exécuter. Si la réponse est positive, l'ID du script sera également inclus dans la réponse.

Cependant, si vous recevez une autre réponse, la documentation d'aide contient une liste complète de chaque code de réponse pour vous aider à diagnostiquer le problème. L'emplacement de la documentation est indiqué dans la section Référence de l'API ci-dessous.

Actions sur la base de données

Lorsque vous travaillez avec des actions sur la base de données, vous devez spécifier la connexion à la base de données. Contrairement aux intégrations, vous ne pouvez pas le faire via la boîte de dialogue de l'action. Cela se fait dans l'une des propriétés de l'action.

Pour configurer la connexion, vous aurez besoin d'un fichier de connexion pour indiquer à l'API ce que vous souhaitez. Ce fichier de connexion définit la connexion à la base de données ainsi que tous les paramètres que vous avez spécifiés, comme du SQL personnalisé ou des alias.

Pour créer un fichier de connexion à la base de données, commencez par configurer la connexion dans BarTender Designer en vous connectant à une base de données. Une fois la connexion établie, si la boîte de dialogue de la base de données n'est pas ouverte, allez dans Fichier > Configuration de la connexion à la base de données pour l'ouvrir. En bas de la boîte de dialogue, cliquez sur le bouton Exporter.

Cela enregistrera les informations de connexion au format XML. Votre nom d'utilisateur, mot de passe et autres informations d'identification sont masqués et ne sont pas enregistrés en clair.

Une fois le fichier créé, vous pouvez l'utiliser dans la propriété ConnectionSetup pour toute action utilisant une connexion à une base de données. Les connexions ne fonctionnent que pour cette action spécifique, donc créez-en une pour chaque action utilisée.

Référence de l'API

Il existe plusieurs endroits dans la documentation d'aide pour vous aider à démarrer. La documentation d'aide se trouve dans BarTender Designer ou en ligne. Une fois Designer ouvert, fermez les pop-ups et allez dans Aide > Aide BarTender. Voici les principaux endroits où trouver la documentation de l'API REST :

Référence BTXML

Si vous utilisez BTXML pour soumettre vos scripts, vous trouverez une référence complète du script BTXML dans le fichier d'aide de BarTender :

Vous y trouverez une introduction à BTXML et une référence complète avec la liste de toutes les balises.

Référence YAML et JSON

YAML et JSON utilisent les mêmes types de variables et de configuration, bien que la mise en forme puisse différer légèrement entre les deux. La référence YAML de BarTender propose une liste complète de toutes les variables, scripts et appels que vous pouvez effectuer dans le fichier d'aide. Vous pouvez la trouver ici.

Lorsque vous ouvrez la référence YAML, vous trouverez une liste de toutes les actions disponibles dans l'API, regroupées par type d'action, ainsi qu'une brève description de chacune. En cliquant sur une action, vous accédez à une page qui liste toutes les propriétés disponibles pour chaque action ainsi qu'un exemple de ce à quoi cela peut ressembler en pratique.

La page principale de la référence YAML explique également comment combiner des actions en groupes et créer des tableaux d'actions à envoyer en un seul script à l'API.

ReDoc

ReDoc est l'un des deux outils que vous pouvez utiliser avec l'API. Il contient des exemples, des informations succinctes sur chaque type de commande et une liste des modèles de réponses que vous pouvez recevoir ainsi que leur signification.

Vous trouverez ReDoc à l'adresse nomduserveur:5159/api/actions/reference/index.html où nomduserveur est le nom de l'ordinateur hébergeant BarTender. Lorsque vous accédez à cette URL dans votre navigateur, vous êtes accueilli par l'API.

Chacune des commandes de l'API peut être trouvée en faisant défiler la page ou en utilisant le menu à gauche pour accéder à la commande souhaitée. Lorsque vous accédez à chaque commande, la barre de droite défile avec vous et propose des sections interactives pour voir des exemples d'appels et de réponses API.

Pour POST, vous avez des exemples de BTXML. Le type de contenu peut être modifié pour passer du BTXML au YAML ou au JSON. Certains exemples proposent un second menu déroulant avec des exemples supplémentaires. Voici une capture d'écran de la commande POST avec un exemple JSON sélectionné

En dessous de l’exemple et de la description de son fonctionnement, vous trouverez une liste des réponses possibles renvoyées par l’API. L’API utilise des codes de réponse HTTP courants, mais chacun a une signification spécifique pour l’API, comme un script au mauvais format ou un client non authentifié.

Chaque type de commande possède un ensemble différent de codes de réponse, et ils sont colorés pour indiquer si la commande a réussi ou non. Les codes verts peuvent être développés pour voir le contenu d’une réponse réussie. Voici un exemple de réponses pour une requête POST :

Swagger

Swagger est une référence API et un outil inclus avec l’installation de la suite BarTender. Il contient une référence complète des scripts et des commandes REST, avec l’avantage supplémentaire de pouvoir l’utiliser pour tester des scripts.

Vous pouvez accéder à Swagger à l’adresse hostname:5159/swagger, où « hostname » correspond au nom de l’ordinateur hébergeant BarTender. Lorsque vous saisissez cette adresse dans votre navigateur, la page d’accueil de la documentation s’affiche.

Chaque commande est cliquable et s’ouvre pour afficher une brève description ainsi qu’un outil de test. En cliquant sur le bouton Try it Out à droite, vous pouvez modifier les valeurs que vous souhaitez envoyer au serveur. Pour Swagger, vous pouvez soit utiliser un fichier texte contenant un script personnalisé, soit partir des exemples proposés dans le corps de la requête en bas de page.

Une fois que vous avez modifié les valeurs et que vous êtes satisfait, faites défiler la page vers le bas et cliquez sur le grand bouton bleu Execute. Cela enverra le script au serveur, qui renverra une réponse.

Par exemple, voici une réponse réussie renvoyée par une commande POST :

Comme avec ReDoc, une liste des réponses possibles se trouve sous l’outil REST. Elle répertorie tous les codes de réponse potentiels avec une brève description. Les codes de réponse réussis comportent également un exemple de ce qui pourrait être renvoyé.

Vous pouvez utiliser Swagger pour tester vos scripts et vous assurer qu’ils fonctionnent correctement avant de les mettre en production. C’est un bon outil pour diagnostiquer et vérifier en temps réel les réponses du système grâce à une représentation visuelle.