Aperçu

BarTender 2022 introduit une API RESTful qui vous permet d’automatiser les travaux d’impression en utilisant des appels REST. Les API REST sont la méthode moderne permettant aux applications et aux systèmes d’échanger des données entre eux sur un réseau ou sur Internet. Les requêtes exécutent des fonctions basées sur les ressources du serveur qui peuvent modifier leur état/forme/statut, mais aussi effectuer des actions côté serveur associées. Si vous avez utilisé l’API REST Print Portal ou toute autre API REST, ce style d’appels vous sera familier. Contrairement aux API mentionnées ci-dessus, le fonctionnement de ces appels est plus similaire aux actions d’Integration Builder ou de Process Builder.

Applicable à

BarTender 2022 et versions ultérieures

Édition Automation ou supérieure

Informations

Exigences de l’API REST

• Version : BarTender 2022 R1 et ultérieures
• Édition : Automation ou Enterprise
• Application émettrice : Custom, 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
• Installation de BarTender pour recevoir les commandes

L’API utilise le port 5159 ; ce port doit donc être ouvert pour recevoir les commandes REST.

Sécurité

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

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

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

Lors de l’utilisation d’Insomnia ou de Postman pour envoyer des requêtes, définissez l’authentification sur NTLM.

Lors de l’utilisation d’IWA, le compte qui envoie les requêtes REST doit avoir les propriétés suivantes :

• L’utilisateur envoyant la requête doit avoir l’autorisation de se connecter au serveur
• L’utilisateur doit avoir les droits pour administrer les intégrations définis dans la console d’administration

Utiliser l’authentification basique

L’authentification basique est désactivée par défaut. Pour l’activer :

1. Accédez à C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 si vous utilisez la dernière version).
2. Trouvez appsettings.json.
3. Faites défiler jusqu’à AuthenticationSchemes en bas et changez Basic de False à True
4. Enregistrez le fichier.
5. Ouvrez la console d’administration.
6. Allez dans Services Windows dans le menu de gauche et redémarrez le service d’intégration BarTender.

Utiliser HTTPS

L’API REST est basée sur le serveur HTTP de Windows (Http.sys). Cependant, vous pouvez la configurer pour utiliser HTTPS afin de sécuriser vos connexions. 

Comme pour la configuration HTTPS des intégrations, vous redirigerez les requêtes REST via Print Portal. Vous aurez besoin d’un certificat SSL, soit d’une autorité de certification, soit auto-signé.

1. D’abord, sécurisez Print Portal avec HTTPS en utilisant votre certificat SSL
2. Dirigez 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 REST API

L’API REST de BarTender utilise seulement trois commandes REST : POST, GET et PATCH. Voici un aperçu de leur fonctionnement.

Les identifiants (ID) sont utilisés pour travailler avec toute action déployée. Lorsqu’un script est POSTé, l’ID figure 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 (60 minutes par défaut, modifiable dans le message POST).

Les variables récupérables via GET fonctionnent comme celles d’une intégration. Vous pouvez récupérer des variables d’intégration et globales ainsi que toutes les variables locales créées par des actions POST. Les valeurs seront liées à l’ID de script soumis.

Scripts POST

Lors de l'utilisation d'une commande POST, vous pouvez demander à BarTender d’exécuter diverses actions et de laisser ces actions actives après l’envoi. Par défaut, une action reste active pendant 60 minutes, mais cette durée est modifiable.

POST permet d’indiquer différentes actions à BarTender selon ce que vous souhaitez faire. 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 que celles utilisées par ces deux 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 – Rechercher et remplacer, Rechercher et supprimer, etc.
• Actions sur les bases de données – Exécuter du SQL, Transformer du texte en jeu d’enregistrements, Pour chaque enregistrement de 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 rédigées en script BTXML, YAML ou JSON. Si vous disposez déjà d’une intégration BTXML fonctionnelle, utiliser BTXML peut être la transition la plus rapide. Voici un exemple de script BTXML d’impression :

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

Après l’envoi du POST, l’API renverra une réponse contenant un code d’état indiquant si le script a été accepté ou non. Recherchez le code 201, qui indique que le script a été accepté et programmé pour s’exécuter. Si la réponse est positive, l’ID du script sera également inclus.

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

Actions sur les bases de données

Lors de l’utilisation d’actions sur les bases de données, vous devez spécifier la connexion à la base de données. Contrairement aux intégrations, cela ne peut pas être fait via la boîte de dialogue de l’action, mais dans l’une des propriétés de l’action.

Pour configurer la connexion, vous avez besoin d’un fichier de connexion indiquant à l’API ce que vous souhaitez. Ce fichier définit la connexion à la base de données ainsi que les paramètres configurés, comme le SQL personnalisé ou les alias.

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

Cela enregistre 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 texte brut.

Une fois le fichier disponible, vous pouvez l’utiliser dans la propriété ConnectionSetup pour toute action nécessitant une connexion à une base. Les connexions ne fonctionnent que pour cette action spécifique, vous devez donc en définir une pour chaque action.

Référence API

Plusieurs sections de la documentation d’aide peuvent vous aider à démarrer. La documentation est disponible dans BarTender Designer ou en ligne. Une fois Designer ouvert, fermez les fenêtres contextuelles et allez dans Aide > Aide BarTender. Voici les sections clés pour la documentation REST API :

Référence BTXML

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

Vous y trouverez une introduction à BTXML ainsi qu’une référence complète listant toutes les balises disponibles.

Référence YAML et JSON

YAML et JSON utilisent les mêmes types de variables et de configuration, bien que leur formatage diffère légèrement. La référence YAML de BarTender contient une liste complète des variables, scripts et appels utilisables. 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 courte description. En cliquant sur une action, vous accédez à une page listant toutes ses propriétés et un exemple pratique.

La page principale de la référence YAML explique également comment combiner plusieurs 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 utilisables avec l’API. Il contient des exemples, des informations succinctes sur chaque type de commande et une liste des modèles de réponse possibles avec leur signification.

Vous trouverez ReDoc à l’adresse hostname:5159/api/actions/reference/index.html où hostname est le nom de l’ordinateur hébergeant BarTender. En accédant à cette URL dans votre navigateur, vous accédez à l’API.

Chaque commande de l’API peut être consultée en faisant défiler la page ou via le menu à gauche. Lorsque vous sélectionnez une commande, la barre de droite défile en même temps et contient des sections interactives permettant de voir des exemples d’appels et de réponses.

Pour POST, des exemples BTXML sont fournis. Vous pouvez changer le type de contenu pour passer entre BTXML, YAML et JSON. Certains exemples offrent un deuxième menu déroulant avec d’autres variantes. Voici une capture d’écran de la commande POST avec un exemple JSON sélectionné :

Sous l’exemple et sa description se trouve une liste des réponses possibles envoyées par l’API. L’API utilise des codes de réponse HTTP courants, mais chacun a une signification spécifique (par exemple, script au mauvais format ou client non authentifié).

Chaque type de commande possède un ensemble différent de codes de réponse, codés par couleur pour indiquer si la commande a réussi ou non. Les codes verts peuvent être développés pour afficher le contenu d’une réponse réussie. Voici un exemple pour POST :

Swagger

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

Vous trouverez Swagger à hostname:5159/swagger où hostname est le nom de l’ordinateur hébergeant BarTender. En entrant cette adresse dans votre navigateur, vous accéderez à la page d’accueil de la documentation.

Chaque commande est cliquable et s’étend pour afficher une brève description ainsi qu’un outil de test. Lorsque vous cliquez sur le bouton Try it Out sur la droite, vous pouvez modifier les valeurs à envoyer au serveur. Avec Swagger, vous pouvez soit utiliser un fichier texte contenant un script personnalisé, soit vous appuyer sur les exemples fournis dans le corps de la requête.

Une fois vos valeurs modifiées et satisfaisantes, faites défiler 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 d’une commande POST:

Comme avec ReDoc, une liste de réponses se trouve sous l’outil REST. Elle répertorie tous les codes de réponse possibles avec une brève description. Les codes de réponse réussis incluent également un exemple de retour.

Vous pouvez utiliser Swagger pour tester vos scripts et vérifier leur bon fonctionnement avant de les utiliser en production. C’est un bon outil pour le dépannage et l’examen des réponses en temps réel grâce à une représentation visuelle du système.