Überblick

BarTender 2022 führt eine RESTful API ein, mit der Sie Druckaufträge mithilfe von REST-Aufrufen automatisieren können. REST-APIs sind die moderne Methode, mit der Anwendungen und Systeme Daten über das Netzwerk oder Internet austauschen. Anfragen führen Funktionen der serverbasierten Ressource aus, die deren Zustand/Form/Status ändern können, aber auch andere serverseitige Aktionen ausführen. Wenn Sie bereits die Print Portal REST API oder eine andere REST API verwendet haben, dürfte Ihnen dieser Stil von API-Aufrufen vertraut vorkommen. Im Gegensatz zu den zuvor genannten APIs funktionieren diese API-Aufrufe jedoch eher wie Aktionen im Integration oder Process Builder.

Gilt für

BarTender 2022 und neuer

Automation Edition oder höher

Informationen

REST API Voraussetzungen

• Version: BarTender 2022 R1 und neuer
• Edition: Automation oder Enterprise Editions
• Sendende Anwendung: Eigenentwickelt, Swagger, Insomnia, Postman
  • Unterstützt IWA, NTLM und Basic-Authentifizierung
  • Unterstützt CORS
  • Curl, C# und .NET-Sprachen werden für eigene Anwendungen unterstützt
• BarTender muss installiert sein, um die Befehle zu empfangen

Die API verwendet Port 5159, daher muss dieser Port geöffnet sein, damit die API die REST-Befehle empfangen kann.

Sicherheit

Die REST API unterstützt verschiedene Authentifizierungsmethoden

• Basic-Authentifizierung
• Integrierte Windows-Authentifizierung (IWA)
• Windows Challenge/Response (NTLM)

Standardmäßig ist die Basic-Authentifizierung deaktiviert.

Wenn Sie Insomnia oder Postman zum Senden von Anfragen verwenden, stellen Sie die Authentifizierung auf NLTM ein.

Bei Verwendung von IWA muss das Konto, das die REST-Anfragen sendet, folgende Eigenschaften haben:

• Der Benutzer, der die Anfrage sendet, muss Anmeldeberechtigung für den Server haben
• Der Benutzer muss Berechtigungen zur Verwaltung von Integrationen haben, wie in der Administration Console festgelegt

Verwendung der Basic-Authentifizierung

Die Basic-Authentifizierung ist standardmäßig deaktiviert. Um sie zu aktivieren, gehen Sie wie folgt vor:

1. Navigieren Sie zu C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0, wenn Sie die neueste Version verwenden).
2. Suchen Sie die Datei appsettings.json.
3. Scrollen Sie nach unten zu AuthenticationSchemes am Ende der Datei und ändern Sie Basic von false auf true (alles klein geschrieben).
4. Speichern Sie die Datei.
5. Öffnen Sie die Administration Console.
6. Navigieren Sie im linken Menü zu Windows-Dienste und starten Sie den BarTender Integration Service neu.

Übertragung über HTTPS

Die REST API basiert auf dem HTTP-Server von Windows (Http.sys). Sie können die REST API jedoch so konfigurieren, dass sie stattdessen HTTPS verwendet, um Ihre Verbindungen zu sichern. 

Ähnlich wie bei der Einrichtung von HTTPS für Integrationen werden die REST-Anfragen über das Print Portal geleitet. Sie benötigen dafür ein SSL-Zertifikat, entweder von einer Zertifizierungsstelle oder ein selbstsigniertes Zertifikat.

1. Sichern Sie zunächst das Print Portal mit HTTPS mithilfe Ihres SSL-Zertifikats.
2. Leiten Sie alle RESTful-Aufrufe an https://localhost/Bartender/api/actions weiter. Ersetzen Sie localhost durch den Servernamen oder die IP-Adresse, falls erforderlich.

REST API Befehle

Die BarTender REST API verwendet nur drei REST-Befehle: POST, GET und PATCH. Hier ein Überblick, wie jeder einzelne mit der API interagiert.

IDs werden verwendet, um mit jeder aktuell ausgeführten Aktion zu arbeiten. Wenn Sie ein Skript per POST senden, ist die ID in der Antwort enthalten, sofern das Skript von der API akzeptiert wurde. Die ID bleibt nur so lange gültig, wie das Skript auf dem API-Server aktiv ist. Standardmäßig sind das 60 Minuten, dieser Wert kann jedoch in der POST-Nachricht geändert werden.

Die Variablen, die Sie mit einem GET abrufen können, sind wie Variablen in einer Integration. Sie können Integrations- und globale Variablen sowie alle lokalen Variablen abrufen, die Sie über POST-Aktionen erstellen. Die abgerufenen Werte beziehen sich immer auf die Skript-ID, die Sie übergeben.

POST-Skripte

Mit einem POST-Befehl können Sie BarTender anweisen, verschiedene Aktionen auszuführen und diese nach dem Absenden weiterlaufen zu lassen. Standardmäßig bleibt eine Aktion 60 Minuten bestehen, dieser Zeitraum ist jedoch anpassbar.

POST ermöglicht verschiedene Aktionen, um BarTender mitzuteilen, was Sie tun möchten. Wenn Sie bereits mit dem Integration Builder oder Process Builder gearbeitet haben, werden Ihnen diese Kategorien bekannt vorkommen, da es sich um die gleichen Befehlstypen handelt, die auch diese Anwendungen verwenden. Hier eine Liste der Kategorien:

• Druckaktionen – Dokument drucken, Befehlsskript, BTXML-Skript
• Eingabeaktionen – Datei lesen, auf serielle Schnittstelle lauschen usw.
• Ausgabeaktionen – Nachricht ins Protokoll schreiben, Web-Service-Anfrage senden usw.
• Ausführungsaktionen – Variable setzen, Shell-Befehl ausführen usw.
• Dateiaktionen – Ordner erstellen, Datei kopieren, Datei löschen usw.
• Transformationsaktionen – Suchen-und-Ersetzen-Aktion, Suchen und Löschen usw.
• Datenbankaktionen – SQL ausführen, Text in Recordset umwandeln, Für jeden Datenbankeintrag usw. (siehe Datenbankabschnitt unten)

Beim Senden eines POST können diese Aktionen in BTXML-Skript, YAML oder JSON geschrieben werden. Wenn Sie bereits eine funktionierende BTXML-Integration haben, ist die Verwendung von BTXML wahrscheinlich der schnellste Weg für Sie. Hier ein Beispiel für ein BTXML-Druckskript:

Wenn Sie bereits mit REST-APIs gearbeitet haben, eine neue API-Schnittstelle erstellen oder einfach mit JSON oder YAML vertrauter sind, kann die API auch diese Formate akzeptieren. Sie sind etwas einfacher und übersichtlicher als BTXML. Hier einige Beispiele in beiden Formaten:

Nach dem Absenden des POST sendet die API eine Antwort zurück. Diese Antwort enthält einen Statuscode, der angibt, ob das Skript akzeptiert wurde oder nicht. Sie sollten nach dem Code 201 Ausschau halten, der anzeigt, dass das Skript akzeptiert wurde und zur Ausführung eingeplant ist. Wenn Sie eine erfolgreiche Antwort erhalten, ist auch die Skript-ID in der Antwort enthalten.

Falls Sie eine andere Antwort erhalten, finden Sie in der Hilfedokumentation eine vollständige Liste aller Antwortcodes, die Ihnen bei der Fehlerdiagnose hilft. Den Speicherort der Dokumentation finden Sie im Abschnitt API-Referenz unten.

Datenbankaktionen

Bei der Arbeit mit Datenbankaktionen müssen Sie die Datenbankverbindung angeben. Anders als bei Integrationen können Sie dies nicht über den Dialog in der Aktion festlegen, sondern dies geschieht über eine Eigenschaft der Aktion.

Um die Verbindung zu konfigurieren, benötigen Sie eine Verbindungsdatei, die der API mitteilt, was Sie möchten. Diese Verbindungsdatei definiert die Datenbankverbindung sowie alle von Ihnen festgelegten Einstellungen wie benutzerdefiniertes SQL oder Aliase. 

Um eine Datenbankverbindungsdatei zu erstellen, richten Sie die Verbindung zunächst im BarTender Designer ein, indem Sie eine Verbindung zu einer Datenbank herstellen. Sobald die Verbindung besteht, öffnen Sie – falls der Datenbankdialog nicht geöffnet ist – über Datei > Datenbankverbindung einrichten den Dialog. Klicken Sie unten im Dialog auf die Schaltfläche Exportieren.

Dadurch werden die Verbindungsinformationen im XML-Format gespeichert. Ihr Benutzername, Passwort und andere identifizierende Informationen werden verschleiert und nicht im Klartext gespeichert.

Sobald Sie die Datei haben, können Sie sie in der Eigenschaft ConnectionSetup für jede Aktion verwenden, die eine Datenbankverbindung benötigt. Die Verbindungen gelten jeweils nur für die spezifische Aktion, richten Sie also für jede Aktion eine eigene Verbindung ein.

API-Referenz

Es gibt mehrere Stellen in der Hilfedokumentation, die Ihnen den Einstieg erleichtern. Die Hilfedokumentation finden Sie im BarTender Designer oder online. Sobald Sie den Designer geöffnet haben, schließen Sie die Popups und gehen Sie zu Hilfe > BarTender-Hilfe. Hier finden Sie wichtige Stellen zur REST API-Dokumentation:

BTXML-Referenz

Wenn Sie BTXML zum Übermitteln Ihrer Skripte verwenden, finden Sie eine vollständige BTXML-Skript-Referenz in der Hilfedatei von BarTender:

Hier finden Sie eine Einführung in BTXML sowie eine vollständige Referenz mit einer Liste aller Tags.

YAML- und JSON-Referenz

YAML und JSON verwenden die gleichen Variablentypen und Strukturen, wobei sich das Format geringfügig unterscheiden kann. Die YAML-Referenz von BarTender enthält eine umfassende Liste aller Variablen, Skripte und Aufrufe, die Sie in der Hilfedatei finden können. Sie finden diese hier.

Wenn Sie die YAML-Referenz öffnen, finden Sie eine Liste aller verfügbaren Aktionen innerhalb der API, gruppiert nach Aktionstyp, sowie eine kurze Beschreibung jeder Aktion. Ein Klick auf die Aktion führt Sie zu einer Seite, auf der alle verfügbaren Eigenschaften sowie ein Beispiel für die praktische Anwendung aufgeführt sind.

Auf der Hauptseite der YAML-Referenz wird außerdem beschrieben, wie Sie Aktionen zu Gruppen zusammenfassen und Arrays von Aktionen erstellen, die als ein einziges Skript an die API gesendet werden können.

ReDoc

ReDoc ist eines von zwei Tools, die Sie mit der API verwenden können. Es enthält Beispiele, kurze Informationen zu jedem Befehlstyp und eine Liste von Antwortmustern, die Sie erhalten können, sowie deren Bedeutung.

Sie finden ReDoc unter hostname:5159/api/actions/reference/index.html, wobei hostname der Name des Computers ist, auf dem BarTender läuft. Wenn Sie diese URL in Ihrem Browser aufrufen, werden Sie von der API begrüßt.

Jeder der API-Befehle kann entweder durch Scrollen auf der Seite oder über das Menü auf der linken Seite aufgerufen werden. Wenn Sie zu einem Befehl navigieren, scrollt die rechte Leiste mit und enthält interaktive Abschnitte, in denen Sie Beispiel-API-Aufrufe und Antworten sehen können.

Für POST werden Ihnen Beispiel-BTXML angezeigt. Der Inhaltstyp kann geändert werden, um das Format zwischen BTXML, YAML und JSON zu wechseln. Einige Beispiele haben ein zweites Dropdown-Menü mit weiteren Beispielen. Hier ein Screenshot des POST-Befehls mit ausgewähltem JSON-Beispiel

Unterhalb des Beispiels und der Beschreibung, wie das Beispiel funktioniert, findest du eine Liste möglicher Antworten, die von der API zurückgegeben werden. Die API verwendet gängige HTTP-Antwortcodes, wobei jeder Code eine spezifische Bedeutung für die API hat, zum Beispiel wenn das Skript im falschen Format ist oder der Client kein authentifizierter Benutzer ist.

Jeder Befehlstyp hat eine eigene Auswahl an Antwortcodes, die farblich gekennzeichnet sind, um anzuzeigen, ob der Befehl erfolgreich war oder nicht. Die grünen Codes lassen sich ausklappen, um zu sehen, was in einer erfolgreichen Antwort enthalten ist. Hier ist ein Beispiel für Antworten auf einen POST-Befehl:

Swagger

Swagger ist eine API-Referenz und ein Tool, das mit der Installation der BarTender Suite mitgeliefert wird. Es enthält eine vollständige Referenz für Skripte und REST-Befehle und bietet zusätzlich die Möglichkeit, Skripte direkt zu testen.

Swagger findest du unter hostname:5159/swagger, wobei „hostname“ der Name des Computers ist, auf dem BarTender läuft. Wenn du diese Adresse in deinen Webbrowser eingibst, öffnet sich die Startseite der Dokumentation.

Jeder Befehl ist anklickbar und lässt sich ausklappen, um eine kurze Beschreibung sowie ein Test-Tool anzuzeigen. Wenn du auf die Schaltfläche Try it Out auf der rechten Seite klickst, kannst du die Werte bearbeiten, die du an den Server senden möchtest. Bei Swagger kannst du entweder eine Textdatei mit einem eigenen Skript verwenden oder die Beispiele im unteren Bereich des Anfragekörpers als Grundlage nehmen.

Nachdem du die Werte angepasst hast und zufrieden bist, scrolle nach unten und klicke auf den großen blauen Execute-Button. Dadurch wird das Skript an den Server gesendet, der dann eine Antwort zurückschickt.

Hier siehst du zum Beispiel eine erfolgreiche Antwort auf einen POST-Befehl:

Wie auch bei ReDoc gibt es unter dem REST-Tool eine Liste mit möglichen Antworten. Dort findest du alle potenziellen Antwortcodes sowie eine kurze Beschreibung. Bei erfolgreichen Antwortcodes gibt es außerdem ein Beispiel, wie eine Rückmeldung aussehen könnte.

Du kannst Swagger nutzen, um deine Skripte zu testen und sicherzustellen, dass sie korrekt funktionieren, bevor du sie in den Produktivbetrieb übernimmst. Es ist ein hilfreiches Tool zur Fehlersuche und um die Antwortmuster des Systems in Echtzeit visuell zu überprüfen.