Création d'une intégration de service web sécurisée
Aperçu
Les intégrations de services web sont un excellent moyen d’automatiser l’impression via une requête web. Ces requêtes se font via HTTP, qui n’est pas sécurisé. Est-il possible d’envoyer cela via HTTPS et de sécuriser les données dans la requête web ?
C’est possible, mais pas directement via Integration Builder ou la Console d’administration. À la place, vous envoyez une requête web à BarTender Print Portal, l’application web de BarTender. BarTender Print Portal dispose d’une fonctionnalité sécurisée appelée Integration Passthrough qui va transférer les requêtes de service web vers l’intégration écoutant sur le même système.
Cet exemple va vous guider pour sécuriser Internet Information Services (IIS) utilisé par BarTender Print Portal, votre intégration et votre fichier d’étiquette.
S’applique à
BarTender 2021 à BarTender 2022 R4
Print Portal
Prérequis
Pour utiliser la fonctionnalité Integration Passthrough de BarTender Print Portal, vous aurez besoin des éléments suivants :
- Internet Information Services (IIS) Manager. Il s’agit d’une fonctionnalité Windows qui peut être installée via l’application Activer ou désactiver des fonctionnalités Windows.
- BarTender Print Portal
- Une application pour envoyer la requête web. Ce tutoriel couvre Postman et Insomnia, mais vous pouvez utiliser celle de votre choix.
Voici également les documents d’exemple pour suivre ce tutoriel :
Activation de HTTPS
Pour sécuriser la connexion pour l’Integration Passthrough, vous devez lier HTTPS à BarTender Print Portal. Cela se fait dans le gestionnaire IIS.
Microsoft propose un guide étape par étape sur comment configurer votre site web pour HTTPS. Par défaut, BarTender Print Portal apparaît sous le nom BarTender dans la liste des sites du gestionnaire IIS. Ce guide explique comment créer et utiliser un certificat auto-signé. Cependant, si vous disposez d’un certificat d’une autorité de certification, vous pouvez suivre les mêmes étapes (en sautant la partie sur l’auto-signé) pour utiliser votre propre certificat.
Une fois la liaison terminée, vous verrez HTTP et HTTPS listés dans la section des liaisons du site comme sur la capture d’écran ci-dessous :
Il n’est pas nécessaire de redémarrer le site ou le système. La liaison prend effet immédiatement dès que vous l’appliquez.
Activation de l’Integration Passthrough
Integration Passthrough est un paramètre dans le fichier de configuration de BarTender Print Portal. Par défaut, ce paramètre est désactivé, donc si vous essayez d’envoyer une requête web maintenant, BarTender Print Portal l’ignorera.
Pour modifier ce paramètre, vous devez ouvrir le fichier de configuration dans une application d’édition de texte en tant qu’administrateur ou avec une application capable de s’élever. Windows ne vous permettra pas d’enregistrer le fichier en tant qu’utilisateur standard. Veuillez suivre les étapes suivantes :
- Si vous utilisez Notepad :
- Trouvez Notepad dans votre menu Démarrer.
- Faites un clic droit et lancez-le en tant qu’Administrateur.
- Allez dans C:\inetpub\wwwroot\BarTender\ puis ouvrez settings.xml
- Descendez vers le bas du fichier et trouvez le paramètre IntegrationPassthrough
- Changez Enabled en "true"
Une fois le fichier enregistré, vous devrez redémarrer plusieurs composants pour que tout ce qui utilise le Passthrough sache qu’il est activé.
Redémarrer les services
- Ouvrez le module Services depuis le menu Démarrer ou le Panneau de configuration.
- Faites un clic droit sur BarTender System Service et sélectionnez Redémarrer.
- Un message vous informera que les dépendances seront également redémarrées. Cliquez sur OK.
- Une fois les boîtes de dialogue fermées, tous les services BarTender devraient indiquer "en cours d’exécution" à côté de leur nom.
Redémarrer le pool d’applications IIS
- Ouvrez le gestionnaire IIS
- Cliquez sur Pools d’applications
- Cliquez sur BPP_AppPool
- Cliquez sur Arrêter dans la liste d’actions à droite, attendez un instant, puis cliquez sur Démarrer.
Configuration de l’intégration
L’intégration elle-même peut être configurée comme toute autre intégration de service web. Voici un bref aperçu de la configuration pour chaque type de requête web :
GET
- L’étiquette doit utiliser des sources de données nommées.
- L’intégration doit remplacer les sources de données nommées dans l’action Imprimer le document.
- Un seul enregistrement est envoyé dans l’URL de la requête.
POST
Il existe deux configurations différentes pour une requête POST selon le nombre d’enregistrements envoyés.
Si vous souhaitez envoyer un seul enregistrement, vous pouvez configurer l’intégration et le fichier d’étiquette de la même manière qu’une requête GET. Les données sont envoyées dans le corps de la requête au lieu de l’URL.
Si vous souhaitez envoyer plusieurs enregistrements, la configuration est la suivante :
- L’étiquette est connectée à une base de données texte comme JSON ou CSV.
- L’intégration remplace la base de données dans l’action Imprimer le document pour utiliser %EventData%.
- Un ou plusieurs enregistrements sont envoyés dans le corps de la requête au même format que la base de données texte connectée à l’étiquette.
Pour cet exemple, les fichiers fournis sont un seul enregistrement pouvant être envoyé par une requête GET ou POST. C’est une configuration assez courante et la plus simple à mettre en place.
Pour plus d’informations et de dépannage, vous pouvez consulter ces articles :
- Puis-je envoyer plusieurs enregistrements dans une intégration de service web ?
- Guide de dépannage : Intégrations
Décompresser l’exemple
Veuillez suivre ces étapes pour décompresser l’exemple et le configurer :
- Téléchargez le pack d’exemple : TempIntegration.zip
- Décompressez les fichiers d’intégration et d’étiquette dans C:\TempIntegration\
- Ouvrez l’intégration
- Cliquez sur l’action Imprimer le document puis sur l’onglet Options d’impression.
- Changez l’imprimante pour une imprimante installée sur votre système.
Configuration de la requête
Pour cette section, vous aurez besoin d’Insomnia, Postman ou d’une application similaire pour envoyer une requête web. Pour POST et GET, l’URL de la requête nécessite une URL d’intégration. Vous pouvez trouver cette URL dans Integration Builder dans la section Service. Cette capture d’écran provient du fichier d’intégration d’exemple. La section surlignée en jaune correspond à l’URL d’intégration :
Si vous avez déjà utilisé des intégrations de services web, cette URL devrait vous sembler familière. Lors de l’envoi d’une requête de service web classique, vous envoyez la requête à ce chemin d’URL complet pour déclencher l’impression via l’intégration. Mais avec le passthrough, on envoie la requête à BarTender Print Portal, qui doit savoir à quelle intégration la transmettre. On lui indique cela en fournissant l’URL d’intégration.
Pour GET et POST, l’URL de la requête web sera au format suivant :
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]
Notez que cette URL est différente de celle indiquée dans le fichier d’intégration. Elle envoie la requête via l’Integration Passthrough qui la transmet ensuite à la targetURL.
Pour nos fichiers d’exemple, en remplissant l’URL d’intégration, l’URL complète de la requête sera :
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
Les exemples suivants utilisent l’URL ci-dessus. Si vous utilisez vos propres fichiers, remplacez l’URL d’intégration d’exemple par celle correspondant à votre propre intégration.
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute
Créer une requête GET
Une requête GET envoie toutes les informations dans l’URL. Cela se fait souvent en remplissant les informations d’en-tête. Cependant, comme l’Integration Passthrough nécessite le paramètre targetURL, les données de l’étiquette doivent être placées à un autre endroit.
Pour Insomnia (voir la capture ci-dessous), l’emplacement approprié est Query. Pour Postman, il s’agit de Params.
Si vous construisez votre propre URL, ajoutez chaque paramètre à l’URL sous forme de paire clé-valeur, séparées par un & comme dans l’aperçu d’URL de la capture ci-dessus.
Voici les données utilisées dans cet exemple :
- URL : https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Paires clé-valeur :
- Company : company
- IDNumber : 3
Créer une requête POST
Une requête POST envoie les données dans le corps de la requête au lieu de l’URL. Comme pour la requête GET, la requête POST utilise le paramètre targetURL pour indiquer à l’Integration Passthrough où envoyer les informations.
Si vous avez regardé tous les paramètres dans le fichier d’intégration, vous avez peut-être remarqué que les données d’entrée sont définies sur JSON. L’intégration est capable d’analyser automatiquement les paires clé-valeur JSON en variables utilisables sans que vous ayez à faire quoi que ce soit de plus ou à ajouter d’actions. Si vous prévoyez d’envoyer un seul enregistrement, cette option peut vous convenir.
Voici les données utilisées dans cet exemple :
- URL : https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Données du corps : {"Company": "The Company", "IDNumber": "3"}
Envoyer la requête
Une fois tout configuré, vous êtes prêt à envoyer votre requête.
- Démarrez l’intégration. Cliquez sur l’onglet Test puis sur le gros bouton vert Démarrer
- Dans l’application Insomnia ou Postman, cliquez sur le bouton Envoyer. Si vous utilisez une application personnalisée, lancez la requête normalement.
- Revenez à l’intégration. Vous devriez voir des messages apparaître dans la section des messages.
- Une fois que vous voyez le message indiquant que le travail a été envoyé au spooler, félicitations. Vous avez envoyé la requête via le système Integration Passthrough et imprimé une étiquette.
Dépannage
Ça ne s’est pas passé comme prévu ? Voici quelques problèmes courants que vous pouvez rencontrer.
Le certificat SSL du pair ou la clé SSH distante n’est pas valide
Lors de l’envoi de la requête pour la première fois, cette erreur apparaît (capture d’écran d’Insomnia) :
Cette erreur apparaît lorsque vous utilisez un certificat auto-signé. Désactivez simplement la validation SSL et renvoyez la requête.
404 Not Found
Lors de l’envoi de la requête, vous obtenez le message d’erreur suivant en réponse du service Integration Passthrough (capture d’écran d’Insomnia) :
Voici les causes courantes de cette erreur :
Cette erreur peut indiquer que l’intégration elle-même n’est pas en cours d’exécution. Lorsque le Passthrough tente de transférer l’information, il n’y a pas d’intégration pour la recevoir. Le service Passthrough suppose alors que l’URL est incorrecte et vous répond avec un 404 Not Found. Assurez-vous de démarrer votre intégration avant d’y envoyer des données.
Cette erreur peut aussi indiquer que le paramètre targetURL est manquant ou incorrect. Consultez la section Configuration de la requête pour vérifier que votre URL est correcte et savoir comment trouver l’URL d’intégration.
De plus, cette erreur peut indiquer que l’Integration Passthrough n’est pas activé. Consultez la section Integration Passthrough pour savoir comment l’activer.
Les données s’impriment sous forme de %NomVariable% au lieu d’une valeur réelle
Sur votre étiquette, vous pouvez voir des valeurs avec % au lieu d’informations réelles. La notation % indique une variable dans le langage de l’intégration. Lorsque l’intégration n’a pas de valeurs à insérer dans ces variables, elle envoie simplement le nom de la variable à imprimer.
Quand cela arrive, la valeur (côté gauche) n’est pas correctement saisie dans votre application de requête web ou est manquante. La valeur doit correspondre aux variables listées dans l’intégration. Ces variables se trouvent dans l’action Imprimer le document, onglet Sources de données nommées. Remarquez sur la capture ci-dessous comment les valeurs d’Insomnia (en noir) correspondent aux noms de variables dans l’intégration (en blanc) :
C’est la même chose avec les données JSON de l’exemple POST.
Pour les requêtes GET uniquement, si vous constatez que les sources de données nommées sont correctement configurées et correspondent aux données envoyées mais que vous voyez toujours les noms de variables, vérifiez où vous placez les données à envoyer. Si vous mettez les données dans la section Header (pour Insomnia et Postman), ces données ne sont pas transmises via le service Integration Passthrough. Retournez à la section Configuration de la requête pour vous assurer que vous placez les données au bon endroit.
Erreurs d’intégration
Vous rencontrez une erreur d'intégration ? Consultez ce guide détaillé : Guide de dépannage : Intégrations