Erstellen einer sicheren Webdienstintegration
Überblick
Webdienst-Integrationen sind eine großartige Möglichkeit, das Drucken über eine Webanfrage zu automatisieren. Diese Anfragen laufen über HTTP, was unsicher ist. Ist es möglich, dies über HTTPS zu senden und die Daten innerhalb der Webanfrage abzusichern?
Das ist möglich, allerdings nicht direkt über den Integration Builder oder die Administration Console. Stattdessen senden Sie eine Webanfrage an das BarTender Print Portal, die Webanwendung von BarTender. Das BarTender Print Portal verfügt über eine sichere Integration Passthrough-Funktion, die Webdienstanfragen an die Integration weiterleitet, die auf demselben System läuft.
In diesem Beispiel zeigen wir Ihnen, wie Sie den Internet Information Services (IIS) unter dem BarTender Print Portal, Ihre Integration und Ihre Etikettendatei absichern.
Gilt für
BarTender 2021 bis BarTender 2022 R4
Print Portal
Voraussetzungen
Um die Integration Passthrough-Funktion des BarTender Print Portals zu nutzen, benötigen Sie Folgendes:
- Internet Information Services (IIS) Manager. Dies ist eine Windows-Funktion und kann über die Anwendung Windows-Features aktivieren oder deaktivieren installiert werden.
- BarTender Print Portal
- Eine Anwendung, um die Webanfrage zu senden. In diesem Tutorial werden Postman und Insomnia behandelt, Sie können aber jede beliebige Anwendung verwenden.
Zusätzlich finden Sie hier die Beispieldateien, um diesem Beispiel zu folgen:
HTTPS aktivieren
Um die Verbindung für das Integration Passthrough abzusichern, müssen Sie HTTPS an das BarTender Print Portal binden. Dies geschieht im IIS Manager.
Microsoft bietet eine Schritt-für-Schritt-Anleitung, wie Sie Ihre Website für HTTPS konfigurieren. Standardmäßig ist das BarTender Print Portal im IIS Manager unter Sites als BarTender aufgeführt. Diese Anleitung beschreibt, wie Sie ein selbstsigniertes Zertifikat erstellen und verwenden. Wenn Sie jedoch ein Zertifikat von einer Zertifizierungsstelle haben, können Sie die gleichen Schritte befolgen (den Abschnitt zum selbstsignierten Zertifikat überspringen), um Ihr Zertifikat zu verwenden.
Nachdem Sie die Bindung abgeschlossen haben, sehen Sie sowohl HTTP als auch HTTPS im Abschnitt Site Bindings, wie im Screenshot unten:
Es ist nicht nötig, die Website oder das System neu zu starten. Die Bindung wird sofort wirksam, sobald Sie sie gesetzt haben.
Integration Passthrough aktivieren
Integration Passthrough ist eine Einstellung in der Konfigurationsdatei des BarTender Print Portals. Standardmäßig ist diese Einstellung deaktiviert. Wenn Sie jetzt eine Webanfrage senden, wird sie vom BarTender Print Portal ignoriert.
Um die Einstellung zu ändern, müssen Sie die Einstellungsdatei in einer Textbearbeitungs-App als Administrator oder mit einer App öffnen, die sich selbst erhöhen kann. Windows erlaubt es Ihnen nicht, die Datei als Standardbenutzer zu speichern. Gehen Sie bitte wie folgt vor:
- Wenn Sie Notepad verwenden:
- Suchen Sie Notepad im Startmenü.
- Klicken Sie mit der rechten Maustaste darauf und wählen Sie Als Administrator ausführen.
- Wechseln Sie zu C:\inetpub\wwwroot\BarTender\ und öffnen Sie settings.xml
- Scrollen Sie fast ganz nach unten und suchen Sie den Parameter IntegrationPassthrough
- Ändern Sie Enabled auf "true"
Nachdem Sie die Datei gespeichert haben, müssen Sie mehrere Komponenten neu starten, damit alle Teile, die mit dem Passthrough arbeiten, wissen, dass es aktiviert ist.
Dienste neu starten
- Öffnen Sie das Dienste-Snap-In über das Startmenü oder die Systemsteuerung.
- Klicken Sie mit der rechten Maustaste auf BarTender System Service und wählen Sie Neu starten.
- Sie werden benachrichtigt, dass auch Abhängigkeiten neu gestartet werden. Klicken Sie auf OK.
- Nachdem die Dialoge verschwunden sind, sollte bei allen BarTender-Diensten "Wird ausgeführt" neben dem Namen stehen.
IIS App Pool neu starten
- Öffnen Sie den IIS Manager
- Klicken Sie auf Anwendungspools
- Klicken Sie auf BPP_AppPool
- Klicken Sie in der Aktionsleiste rechts auf Stoppen, warten Sie einen Moment und klicken Sie dann auf Starten.
Integration einrichten
Die Integration selbst kann ähnlich wie jede andere Webdienst-Integration eingerichtet werden. Hier ein kurzer Überblick über die Einrichtung für jeden Typ von Webdienstanfrage:
GET
- Das Etikett muss benannte Datenquellen verwenden.
- Die Integration muss die benannten Datenquellen in der Aktion "Dokument drucken" überschreiben.
- Ein einzelner Datensatz wird als Teil der Anfrage-URL gesendet.
POST
Für eine POST-Anfrage gibt es zwei verschiedene Setups, je nachdem, wie viele Datensätze Sie senden.
Wenn Sie einen einzelnen Datensatz senden möchten, können Sie die Integration und die Etikettendatei genauso wie bei einer GET-Anfrage einrichten. Die Daten werden im Body der Anfrage statt in der URL gesendet.
Wenn Sie mehrere Datensätze senden möchten, ist das Setup wie folgt:
- Das Etikett ist mit einer Textdatenbank wie JSON oder CSV verbunden.
- Die Integration überschreibt die Datenbank in der Aktion "Dokument drucken", um %EventData% zu verwenden.
- Ein oder mehrere Datensätze werden als Body der Anfrage im gleichen Format gesendet, das auch in der mit dem Etikett verbundenen Textdatenbank verwendet wird.
Für dieses Beispiel sind die Beispieldateien ein einzelner Datensatz, der entweder per GET- oder POST-Anfrage gesendet werden kann. Dies ist eine recht gängige Konfiguration und am einfachsten umzusetzen.
Weitere Informationen und Hilfestellungen finden Sie in diesen Artikeln:
- Kann ich mehrere Datensätze in einer Webdienst-Integration senden?
- Leitfaden zur Fehlerbehebung: Integrationen
Beispiel entpacken
Bitte gehen Sie wie folgt vor, um das Beispiel zu entpacken und einzurichten:
- Laden Sie das Beispielpaket herunter: TempIntegration.zip
- Entpacken Sie die Integrations- und Etikettendateien nach C:\TempIntegration\
- Öffnen Sie die Integration
- Klicken Sie auf die Aktion Dokument drucken und dann auf den Tab Druckoptionen.
- Wählen Sie einen Drucker aus, der auf Ihrem System installiert ist.
Anfrage einrichten
Für diesen Abschnitt benötigen Sie Insomnia, Postman oder eine ähnliche Anwendung, um eine Webanfrage zu senden. Für POST und GET benötigt die Anfrage-URL eine Integrations-URL. Diese finden Sie im Integration Builder im Bereich Service. Dieser Screenshot stammt aus der Beispiel-Integrationsdatei. Der gelb markierte Bereich ist die Integrations-URL:
Wenn Sie bereits Webdienst-Integrationen verwendet haben, sollte Ihnen diese URL bekannt vorkommen. Bei einer normalen Webdienst-Anfrage senden Sie die Anfrage an diesen vollständigen URL-Pfad, um die Integration zum Drucken auszulösen. Beim Passthrough senden wir die Anfrage jedoch an das BarTender Print Portal, das wissen muss, an welche Integration sie weitergeleitet werden soll. Das teilen wir ihm mit, indem wir die Integrations-URL angeben.
Für GET und POST sieht die Webanfrage-URL folgendermaßen aus:
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]
Beachten Sie, dass sich diese URL von der in der Integrationsdatei unterscheidet. Sie sendet die Anfrage durch das Integration Passthrough, das sie dann an die targetURL weiterleitet.
Für unsere Beispieldateien ergibt sich mit ausgefüllter Integrations-URL folgende vollständige Anfrage-URL:
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
Die folgenden Beispiele verwenden die oben genannte URL. Wenn Sie eigene Dateien verwenden, ersetzen Sie die Beispiel-Integrations-URL durch die, die zu Ihrer eigenen Integration passt.
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute
Eine GET-Anfrage erstellen
Eine GET-Anfrage sendet alle Informationen in der URL. Dies geschieht häufig durch das Ausfüllen der Header-Informationen. Da das Integration Passthrough jedoch den targetURL-Parameter benötigt, müssen die Etikettendaten an einer anderen Stelle platziert werden.
In Insomnia (siehe Screenshot unten) ist der richtige Ort "Query". In Postman ist es "Params".
Wenn Sie Ihre eigene URL erstellen, fügen Sie jedes Parameterpaar als Schlüssel-Wert-Paar mit einem & zwischen den Paaren an die URL an, wie in der URL-Vorschau im Screenshot oben.
Hier die in diesem Beispiel verwendeten Daten:
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Schlüssel-Wert-Paare:
- Company: company
- IDNumber: 3
Eine POST-Anfrage erstellen
Eine POST-Anfrage sendet die Daten im Body der Anfrage statt in der URL. Ähnlich wie bei der GET-Anfrage gibt es auch hier den targetURL-Parameter, um dem Integration Passthrough mitzuteilen, wohin die Informationen gesendet werden sollen.
Wenn Sie sich alle Einstellungen in der Integrationsdatei angesehen haben, ist Ihnen vielleicht aufgefallen, dass die Eingabedaten auf JSON gesetzt sind. Die Integration kann die JSON-Schlüssel-Wert-Paare automatisch in verwendbare Variablen umwandeln, ohne dass Sie zusätzliche Arbeit oder Aktionen hinzufügen müssen. Wenn Sie nur einen Datensatz senden möchten, ist dies eine gute Option.
Hier die in diesem Beispiel verwendeten Daten:
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Body-Daten: {"Company": "The Company", "IDNumber": "3"}
Anfrage senden
Nachdem alles eingerichtet ist, können Sie Ihre Anfrage senden.
- Starten Sie die Integration. Klicken Sie auf den Tab Testen und dann auf den großen grünen Start-Button.
- Klicken Sie in der Insomnia- oder Postman-App auf den Senden-Button. Wenn Sie eine eigene App verwenden, führen Sie die Anfrage wie gewohnt aus.
- Wechseln Sie zurück zur Integration. Sie sollten Nachrichten im Nachrichtenbereich sehen.
- Sobald Sie die Meldung sehen, dass der Auftrag an den Spooler gesendet wurde, herzlichen Glückwunsch! Sie haben die Anfrage erfolgreich über das Integration Passthrough-System gesendet und ein Etikett gedruckt.
Fehlerbehebung
Hat es nicht wie erwartet funktioniert? Hier sind einige häufige Probleme, auf die Sie stoßen könnten.
SSL Peer Certificate oder SSH Remote Key war nicht OK
Wenn Sie die Anfrage zum ersten Mal senden, erscheint dieser Fehler (Screenshot aus Insomnia):
Dieser Fehler tritt auf, wenn Sie ein selbstsigniertes Zertifikat verwenden. Deaktivieren Sie einfach die SSL-Validierung und senden Sie die Anfrage erneut.
404 Nicht gefunden
Beim Senden der Anfrage erhalten Sie folgende Fehlermeldung als Antwort vom Integration Passthrough-Service (Screenshot aus Insomnia):
Hier sind die häufigsten Ursachen für diesen Fehler:
Dieser Fehler kann darauf hinweisen, dass die Integration selbst nicht läuft. Wenn das Passthrough versucht, die Informationen weiterzuleiten, gibt es keine Integration, die sie empfangen kann. Der Passthrough-Service geht davon aus, dass die URL falsch ist, und antwortet mit einem 404 Not Found. Stellen Sie sicher, dass Sie Ihre Integration zuerst starten, bevor Sie Daten an sie senden.
Dieser Fehler kann auch darauf hinweisen, dass der targetURL-Parameter fehlt oder falsch ist. Überprüfen Sie den Abschnitt Anfrage einrichten, um sicherzustellen, dass Ihre URL korrekt ist und wie Sie die Integrations-URL finden.
Außerdem kann dieser Fehler bedeuten, dass das Integration Passthrough nicht aktiviert ist. Lesen Sie den Abschnitt Integration Passthrough, um zu erfahren, wie Sie dies einrichten.
Daten werden als %Variablenname% statt als Wert gedruckt
Auf Ihrem Etikett sehen Sie möglicherweise Werte mit % statt tatsächlicher Informationen. Die % Notation steht für eine Variable in der Integrationssprache. Wenn die Integration keine Werte für diese Variablen hat, wird einfach der Variablenname zum Drucken gesendet.
Wenn dies passiert, ist der Wert (linke Seite) in Ihrer Webanfrage-App entweder falsch geschrieben oder fehlt. Der Wert muss mit den in der Integration aufgeführten Variablen übereinstimmen. Diese Variablen finden Sie in der Aktion "Dokument drucken" auf dem Tab "Benannte Datenquellen". Im Screenshot unten sehen Sie, wie die Werte aus Insomnia (schwarz) mit den Variablennamen in der Integration (weiß) übereinstimmen:
Das Gleiche gilt für die JSON-Daten aus dem POST-Beispiel.
Nur bei GET-Anfragen: Wenn Sie feststellen, dass die Benannten Datenquellen korrekt eingerichtet sind und mit den gesendeten Daten übereinstimmen, aber dennoch nur Variablennamen angezeigt werden, überprüfen Sie, wo Sie die zu sendenden Daten eingeben. Wenn Sie die Daten im Header-Bereich (sowohl in Insomnia als auch in Postman) platzieren, werden diese Daten nicht durch das Integration Passthrough weitergegeben. Gehen Sie zurück zum Abschnitt Anfrage einrichten, um sicherzustellen, dass Sie die Daten an der richtigen Stelle eingeben.
Integrationsfehler
Erhalten Sie einen Integrationsfehler? Schauen Sie sich diesen ausführlichen Leitfaden an: Fehlerbehebung: Integrationen