Übersicht

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

Geeignet für

BarTender 2022 und neuer

Automation Edition oder höher

Information

REST-API-Anforderungen

• Version: BarTender 2022 R1 und neuer
• Edition: Automation oder Enterprise
• Sendende Anwendung: Custom, Swagger, Insomnia, Postman
  • Unterstützt IWA, NTLM und Basis-Authentifizierung
  • Unterstützt CORS
  • Curl, C# und .NET-Sprachen werden für benutzerdefinierte Anwendungen unterstützt
• BarTender-Installation, um die Befehle zu empfangen

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

Sicherheit

Die REST-API unterstützt mehrere Authentifizierungstypen

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

Standardmäßig ist die Basis-Authentifizierung deaktiviert.

Wenn Sie Insomnia oder Postman verwenden, stellen Sie die Authentifizierung auf NTLM ein.

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

• Der Benutzer, der die Anfrage sendet, muss Berechtigung zum Anmelden am Server haben
• Der Benutzer muss über Berechtigungen zur Verwaltung von Integrationen in der Administrationskonsole verfügen

Basis-Authentifizierung verwenden

Die Basis-Authentifizierung ist standardmäßig deaktiviert. Um sie zu aktivieren:

1. Navigieren Sie zu C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 für die neueste Version).
2. Suchen Sie appsettings.json.
3. Scrollen Sie zu AuthenticationSchemes und ändern Sie Basic von False auf True
4. Speichern Sie die Datei.
5. Öffnen Sie die Administrationskonsole.
6. Navigieren Sie in der linken Menüleiste zu Windows-Dienste und starten Sie den BarTender Integration Service neu.

Über HTTPS senden

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

Ähnlich wie beim Einrichten von HTTPS für Integrationen leiten Sie die REST-Anfragen über das Print Portal weiter. Sie benötigen ein SSL-Zertifikat von einer Zertifizierungsstelle oder ein selbstsigniertes Zertifikat.

1. Sichern Sie zuerst das Print Portal mit HTTPS mit Ihrem SSL-Zertifikat.
2. Leiten Sie alle REST-Aufrufe an https://localhost/Bartender/api/actions. Leiten Sie localhost bei Bedarf auf den Servernamen oder die IP-Adresse um.

REST-API-Befehle

Die BarTender-REST-API verwendet nur drei REST-Befehle: POST, GET und PATCH. Hier ein Überblick über deren Funktionsweise.

IDs werden verwendet, um mit laufenden Aktionen zu arbeiten. Wenn Sie ein Skript POSTen, enthält die Antwort die ID, falls das Skript akzeptiert wurde. Die ID ist nur solange gültig, wie das Skript auf dem Server aktiv ist (standardmäßig 60 Minuten, änderbar in der POST-Nachricht).

Variablen, die Sie mit GET abrufen, funktionieren wie Variablen in einer Integration. Sie können Integrations- und globale Variablen sowie lokale Variablen, die Sie per POST erstellen, abrufen. Die Werte beziehen sich auf die übermittelte Skript-ID.

POST-Skripte

Wenn Sie einen POST-Befehl verwenden, können Sie BarTender anweisen, verschiedene Aktionen auszuführen und diese nach dem Absenden weiterlaufen zu lassen. Standardmäßig bleibt eine Aktion 60 Minuten lang aktiv, aber diese Zeit kann geändert werden.

POST ermöglicht verschiedene Aktionen, um BarTender mitzuteilen, was Sie ausführen möchten. Wenn Sie bereits den Integration Builder oder Process Builder verwendet haben, sollten Ihnen diese Kategorien vertraut vorkommen, da es sich um dieselben Befehlstypen handelt, die auch diese Anwendungen verwenden. Hier ist eine Liste der Kategorien:

• Druckaktionen – Dokument drucken, Befehls-Skript, BTXML-Skript
• Eingabeaktionen – Datei lesen, seriellen Port abhören usw.
• Ausgabeaktionen – Nachricht ins Protokoll schreiben, Webservice-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 Datensatz 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 BTXML möglicherweise der schnellste Übergang für Sie. Hier ist ein Beispiel eines BTXML-Druckskripts:

Wenn Sie bereits mit REST-APIs gearbeitet haben, eine neue API-Schnittstelle erstellen oder einfach besser mit JSON oder YAML vertraut sind, akzeptiert die API ebenfalls diese Aufrufe. Sie sind etwas einfacher und leichter lesbar als BTXML. Hier sind 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. Achten Sie auf den Code 201, der anzeigt, dass das Skript akzeptiert wurde und zur Ausführung geplant ist. Bei einer erfolgreichen Antwort wird auch die Skript-ID in die Antwort aufgenommen.

Wenn Sie jedoch eine andere Antwort erhalten, enthält die Hilfedokumentation eine vollständige Liste aller Antwortcodes, um Ihnen bei der Diagnose des Problems zu helfen. Der Speicherort der Dokumentation ist im Abschnitt API-Referenz unten angegeben.

Datenbankaktionen

Bei der Arbeit mit Datenbankaktionen müssen Sie die Datenbankverbindung angeben. Im Gegensatz zu Integrationen können Sie dies nicht über den Aktionsdialog angeben, sondern in einer der Eigenschaften der Aktion.

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

Um eine Datenbank-Verbindungsdatei zu erstellen, richten Sie zunächst die Verbindung in BarTender Designer ein, indem Sie sich mit einer Datenbank verbinden. Sobald die Verbindung hergestellt ist, und wenn der Datenbankdialog nicht geöffnet ist, gehen Sie zu Datei > Datenbankverbindung einrichten, um ihn zu öffnen. Klicken Sie unten im Dialogfeld auf die Schaltfläche Exportieren.

Dadurch werden die Verbindungsinformationen im XML-Format gespeichert. Ihr Benutzername, Passwort und andere Identifikationsinformationen 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 funktionieren nur für diese spezifische Aktion, daher müssen Sie für jede verwendete Aktion eine eigene Verbindung einrichten.

API-Referenz

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

BTXML-Referenz

Wenn Sie BTXML zum Einreichen 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 vollständigen Liste aller Tags.

YAML- und JSON-Referenz

YAML und JSON verwenden dieselben Arten von Variablen und Strukturen, obwohl das Format zwischen den beiden leicht abweicht. BarTenders YAML-Referenz enthält eine umfassende Liste aller Variablen, Skripte und Aufrufe, die Sie in der Hilfedatei verwenden können. Sie finden sie hier.

Wenn Sie die YAML-Referenz öffnen, finden Sie eine Liste aller in der API verfügbaren Aktionen, gruppiert nach Aktionstyp, sowie eine kurze Beschreibung jeder Aktion. Ein Klick auf die Aktion führt zu einer Seite, die alle verfügbaren Eigenschaften für diese Aktion sowie ein praktisches Beispiel enthält.

Die Hauptseite der YAML-Referenz beschreibt außerdem, wie Aktionen zu Gruppen kombiniert und Arrays von Aktionen erstellt werden, die als einzelnes Skript an die API gesendet werden.

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 gehostet wird. Wenn Sie diese URL in Ihrem Browser aufrufen, werden Sie von der API begrüßt.

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

Für POST werden Ihnen Beispiel-BTXML angezeigt. Der Inhaltstyp kann geändert werden, um zwischen BTXML, YAML und JSON zu wechseln. Einige Beispiele verfügen über ein zweites Dropdown-Menü mit weiteren Beispielen. Hier ist ein Screenshot des POST-Befehls mit einem ausgewählten JSON-Beispiel:

Unter dem Beispiel und der Beschreibung, wie es funktioniert, befindet sich eine Liste möglicher Antworten der API. Die API verwendet gängige HTTP-Antwortcodes, wobei jeder eine spezifische Bedeutung für die API hat, z. B. dass das Skript das falsche Format hat oder der Client nicht authentifiziert ist.

Jeder Befehlstyp hat eine andere Reihe von Antwortcodes, die farbcodiert sind, um anzuzeigen, ob der Befehl erfolgreich war oder nicht. Die grünen Codes können erweitert werden, um den Inhalt einer erfolgreichen Antwort anzuzeigen. Hier ist ein Beispiel für Antworten von POST:

Swagger

Swagger ist eine API-Referenz und ein Tool, das mit der BarTender-Suite installiert wird. Es enthält eine vollständige Referenz der Skripte und REST-Befehle und bietet den zusätzlichen Vorteil, dass Sie es zum Testen Ihrer Skripte verwenden können.

Sie finden Swagger unter hostname:5159/swagger, wobei hostname der Name des Computers ist, auf dem BarTender gehostet wird. Wenn Sie diese Adresse in Ihren Webbrowser eingeben, wird die Startseite der Dokumentation angezeigt.

Jeder Befehl ist anklickbar und erweitert sich, um eine kurze Beschreibung sowie ein Testwerkzeug anzuzeigen. Wenn Sie auf die Schaltfläche Try it Out auf der rechten Seite klicken, können Sie die Werte, die Sie an den Server senden möchten, bearbeiten. Bei Swagger können Sie entweder eine Textdatei mit einem benutzerdefinierten Skript verwenden oder die Beispiele im Anfragetext unten erweitern.

Sobald Sie die Werte bearbeitet haben und zufrieden sind, scrollen Sie nach unten und klicken Sie auf die große blaue Schaltfläche Execute. Dadurch wird das Skript an den Server gesendet, der eine Antwort zurückgibt. 

Hier ist ein Beispiel für eine erfolgreiche Antwort auf einen POST-Befehl:

Genau wie bei ReDoc befindet sich unter dem REST-Tool eine Liste von Antworten. Sie enthält alle möglichen Antwortcodes mit einer kurzen Beschreibung. Die erfolgreichen Antwortcodes enthalten außerdem ein Beispiel, was zurückgegeben werden könnte.

Sie können Swagger als Tool verwenden, um Ihre Skripte zu testen und sicherzustellen, dass sie korrekt funktionieren, bevor Sie sie in die Produktion überführen. Es ist ein gutes Tool zur Fehlersuche und zum Überprüfen der Antwortmuster in Echtzeit mit einer visuellen Darstellung des Systems.