Einstellungen

(1) Vorlage wählen: Diese Vorlagen (mit Voreinstellungen) erhalten Sie im Update-Center.

(2) URL Adressen-Suffix: Der URL-Suffix. Über das Fragezeichen-Icon links sehen Sie den vorderen Teil der Endpoint-URL. Dieser, zusammen mit dem Suffix, ergibt dann die Gesamt-URL. Für Details siehe Abschnitt " Request-Ablauf" unten. Beispiel: "example".

(3) API Variablen: Nur verfügbar im Modus "REST-WebService" (7). Hier können Pfad-Parameter angegeben werden. Es kann genau ein Pfad-Parameter zwischen den Slashes definiert werden (siehe Screenshot). Jeder angegebene Pfad-Parameter kann ausgelesen werden mit einer System-Variable MSG_CALL_HTTP_REST_API_PATH_<Name des Pfad-Parameters> (muss angelegt werden). Beispiel und Hinweise:

Feld "URL-Adressen-Suffix": example/

Feld "API-Variablen": {shop}/{petID}

HTTP-Request: https://<URL/IP Integration Server>/dw/request/example/myshop/4711/something

Hinweise:

• Beachten Sie bitte, dass Sie bei der Angabe von Pfad-Parametern einen Slash am Ende des Suffixes (2) angeben müssen, hier also "example/". Ein führender Slash in Feld (3) wird nach einem Speichern des Profils automatisch entfernt!

• Pfad-Parameter sind Pflichtangaben in Swagger/OpenAPI (8). Wird das Profil direkt angesprochen, sind sie aber optional.

• Siehe auch https://swagger.io/docs/specification/describing-parameters/#path-parameters und https://petstore.swagger.io/.

(4) Erlaubte HTTP-Methoden: Die erlaubten HTTP-Methoden. Wichtiger Hinweis: Siehe Abschnitt "Request-Body, Profil-Verhalten und Profil-Eingangsdaten" unten.

(5) DELETE liefert Daten: Siehe Hinweis in (4).

(6) Asynchrone Rückmeldung: Ist diese Checkbox gesetzt, wird erreicht, dass mehrere Instanzen dieses Profils parallel arbeiten können. Die Checkbox "Profil darf nur in einer Instanz laufen" darf für dieses Profil nicht gesetzt werden. Funktioniert nur bei einer festen Antwort (13). Die Response erfolgt dann sofort und nicht erst, wenn der Profil-Job beendet ist. Hinweis: Ist diese Option gesetzt, werden Jobs dieses Profils in einer Thread Queue abgearbeitet.

(7) HTTP-Schnittstelle, REST-Webservice, SOAP-Webservice: Der Modus des HTTP-Eingangsagenten.

(8) Veröffentliche Schnittstelle (API Dokumentation): Ist diese Checkbox gesetzt, das Mapping aktiv, die Option "REST-WebService" (7) gesetzt und das Profil gespeichert, dann wird eine Swagger-/OpenAPI-Schnittstellenbeschreibung im JSON- oder YAML-Format bereitgestellt. Sie können über (19) auch eigene Swagger-Dateien anlegen, die dann statt der automatisch generierten verwendet werden. Diese Dateien haben den Namen "<Profil-Name>. json" bzw. "<Profil-Name>.yaml" und befinden sich im Verzeichnis ./conf/openapi. Auf den Aufbau dieser Dateien wird hier nicht eingegangen, beziehen Sie sich bitte auf die OpenAPI-Dokumentation. Beispiel: "https://localhost/dw/Request/example?api bzw. https://localhost/dw/Request/example?api&yaml".

Zudem wird Ihnen in einem graphischen Tool eine Swagger-/OpenAPI-Schnittstellenbeschreibung im YAML-Format bereitgestellt, siehe Link (8). Dort können Sie Requests an die Schnittstelle senden. Siehe allgemein Abschnitt "REST API" (Anleitung dort). Die Daten für den Authentifizierungs-Dialog (auch erreichbar über das Zahnrad) entnehmen Sie bitte aus (17). Sie können mehrere solcher Profile zu einer zusammengehörigen REST-API zusammenfassen. Siehe hierzu Abschnitt "Basis-Daten (Data Flow)".

URL: http(s)://<URL oder IP des Integration Servers>/openapi/?endpoint=<URL-Suffix>

Beispiel: https://localhost/openapi/?endpoint=example

Wichtiger Hinweis: Wenn Sie die Schnittstelle ü ber den DMZ-Server verfügbar machen wollen (falls vorhanden und alle Forwarding-Regeln eingerichtet sind) , müssen Sie auf dem inneren Integration Server in der Konfigurationsdatei ./etc/startup.xml im Parameter "webServiceUrl" die IP/URL (und gegebenenfalls den Port) ändern auf die IP/URL des DMZ-Servers. Dieser Parameter wird verwendet, um im graphischen Tool die Server-Adresse zu setzen (siehe folgenden Screenshot). Ist diese nicht korrekt, dann funktionieren die Requests nicht.

Wichtiger Hinweis: Die IP/URL (und gegebenenfalls der Port) im Parameter "webServiceUrl" (siehe Hinweis davor) muss auch angepasst werden auf die öffentliche Adresse des Integration Servers, wenn Sie das graphische Tool extern zur Verfügung stellen wollen (also nicht nur im Intranet).

(9) Testdaten für API: Nur verfügbar im Modus "REST-WebService" (7). Hier werden alle hinterlegten Testdateien in einem weiteren Dialog angezeigt. Dort kann man für jede Datei angeben, für welche HTTP-Methode (4) sie in (8) zur Verfügung stehen. In (8) werden diese dann angezeigt (links) und können für einen Request (rechts) ausgewählt werden (z. B. bei POST). Siehe auch (7).

(10) Content-Type der Antwort: MIME-Type der Response.

(11) Multipart FileKey: Optionaler Name des Multiparts für die Hauptdaten. Normalerweise wird immer nach dem Part mit dem Namen "file" gesucht. Sollte der Name aber nicht "file" sein, kann man den alternativen Part-Namen hier eintragen. Hinweis: Dies gilt nur für Multipart-Requests und wenn kein Part mit dem Namen "file" gefunden wurde! Siehe auch den Abschnitt dazu unten.

(12) Akzeptiere leeren HTTP Body: Ein leerer HTTP-Body (z. B. bei POST) wird nicht als Fehler gesehen.

(13) Antwort senden durch: Die Antwort für den Erfolgsfall kann auf drei verschiedene Arten festgelegt werden. Die Antwort im Fehlerfall wird immer in (15) festgelegt.

• Fester Response-Wert, siehe (14).

• Dynamischer Response-Wert. Verwenden Sie hierzu einen Antwortweg "Eigene Klasse" mit der Klasse "PassBackDataResponse" oder setzen Sie die Option "Daten zurückliefern" in einem Antwortweg "HTTP" oder "Message". Siehe hierzu auch Abschnitt HTTP-Response-Kette.

• Kein Rückgabewert. Wie der Name sagt, ist hier die Response leer. Der Response-Status ist "204".

(14) Antwort bei Erfolg: Fester Response-Wert, siehe (13). Zeilenumbrüche können eingefügt werden mit <br>. Hinweis: Die Platzhalter {--jobnr--} bzw. @VAR_JOBNR@ und {--uuid--} bzw. @VAR_SYS_MESSAGE_ID@ sind verfügbar. Zudem können Variablen der Phase 3 verwendet werden mit {--@MYVAR@--} oder @MYVAR@. Phase 3 muss dazu aktiv sein.

(15) Antwort bei Fehler: Antwort, die im Fehlerfall gesendet wird, für beide Fälle in (13). Hinweis: Es kann hier auch der Platzhalter {--Exception--} verwendet werden, um eine aufgetretene Exception zurück zu geben. Enthält die Exception-Meldung einen Teilstring §...§, dann wird der Platzhalter durch den Teilstringtext ersetzt. Beispiel: Wenn Sie in Phase 3 des Profils die Funktion throw exception("§Sorry!§") aufrufen, dann wird der Platzhalter {--Exception--} durch den String "Sorry!" ersetzt. Alternativ kann der Platzhalter {--FullStackTraceException--} verwendet werden, um den vollen Stacktrace auszugeben.

(16) HTTP-Fehler-Code: Der HTTP-Response-Status-Code, der im Fehlerfall zurückgeschickt wird. Über den Button "Weitere HTTP-Fehler-Codes" rechts, können weitere Codes mit dazugehöriger "Antwort bei Fehler" (15) eingetragen werden. Diese Einträge können verwendet werden von der Funktion "throw http exception(a,b)" (siehe Beschreibung dort).

(17) WWW Authentication: Entweder ohne Zugangskontrolle oder mit Zugangskontrolle über einen oder mehrere ausgewählte HTTP-Kanäle (" Eigener Zugang" ) oder mit direkt angegebenen Zugangsdaten. Wenn eine Zugangskontrolle verwendet wird, kann die Authentication-Methode ("BASIC", "DIGEST", "OAUTH2", "SYSTEM") ausgewählt werden. Siehe auch System-Variable MSG_CALL_HTTP_AUTH_USER.

• Bei "SYSTEM" wird die Einstellung aus der Konfigurationsdatei ./etc/startup.xml (→ forceDigestAuthentication ) verwendet. Wird angezeigt auf Seite "Start".

• Wird " OAUTH2" verwendet, muss auch ein HTTP-Kanal angegeben werden mit OAUTH2-Konfiguration.

(18) Pflicht-Parameter: Festlegung der Pflicht-Request-Parameter. Siehe Abschnitte " Request-Ablauf" und " Request-Parameter" unten für Details.

(19) Burger-Menü rechts von (2): Siehe (8).

Schematischer Aufbau der HTTP-Adresse

Um einem Profil Daten per HTTP zu senden oder es per HTTP zu starten, muss man eine bestimmte URL ansprechen. Der schematische Aufbau der URL ist

Request-Body, Profil-Verhalten und Profil-Eingangsdaten

Je nachdem, welche HTTP-Methode Sie verwenden und ob der HTTP-Request einen Body mit Daten hat oder nicht, verhält sich das Profil unterschiedlich und erhält unterschiedliche Eingangsdaten.

Wichtiger Hinweis: Wenn Sie in Ihrem Profil ein Mapping verwenden, dann müssen die Eingangsdaten ein bestimmtes Format haben, damit kein Fehler beim Parsen entsteht. Beachten Sie dies bitte bei der Auswahl der erlaubten HTTP-Methoden (4). Sie würden in diesem Fall z. B. die HTTP-Methode "POST" erlauben und bestimmte Eingangsdaten im Request-Body erwarten. In diesem Fall würde es also keinen Sinn machen auch die HTTP-Methode "GET" zu erlauben, da die Eingangsdaten, die das Profil dann erhält, nicht zur Quellstruktur des Profils passen und dadurch ein Fehler beim Parsen entsteht.

Hinweis: In der folgenden Tabelle wird davon ausgegangen, dass die entsprechende HTTP-Methode in (4) selektiert ist. Erhält das Profil einen Request mit einer Methode, die nicht in (4) selektiert ist, wird kein Job gestartet und das Profil liefert als Response den String "Your request could not be processed due to unknown/mismatched parameters" und den Response-Status-Code "404".

Hinweis: Tritt einer der in diesem Abschnitt beschriebenen Fehler auf, dann gelten die folgenden Abschnitte zu Request und Response nicht.

Request-Ablauf

Das HTTP-Servlet wird beim Start des Integration Servers gestartet und reagiert per Default sowohl auf den HTTP-Kontext "/dw/request" als auch "/dw/Request".

Bei einem eingehenden Request wird vom HTTP-Servlet zunächst das korrekte Profil gesucht. Dabei werden alle aktiven Profile in Betracht gezogen, die einen eventgesteuerten HTTP-Eingangsagenten haben und deren Suffix (2) dem Suffix im Request entspricht.

Zusätzlich müssen die Request-Parameter zu den Pflicht-Request-Parametern (18) passen. Sind z. B. in (1) der Wert "example" und in der Parameterliste (18) zwei Parameter (p1=value1, p2=value2) eingetragen, dann muss die URL wie folgt aussehen.

Das erste passende Profil wird ausgewählt und die Verarbeitung angestoßen. Verlangt das Profil eine Authentifizierung (17), wird das Profil aber erst nach erfolgreicher Authentifizierung gestartet. Falls weitere Profile den Bedingungen entsprechen, werden diese Profile nicht berücksichtigt.

Request-Parameter

Request-Header

Request-Header können ausgelesen werden mit den System-Variablen MSG_CALL_HEADER_HTTP_<Name des Headers in Großbuchstaben>. Hinweis: Die System-Variable MSG_CALL_HEADER_HTTP_AUTHORIZATION (Header "Authorization") wird per Default nicht gesetzt. Mit der System-Property "hub.datawizard.http.copy.allHeader=true" können Sie ein Setzen dieser Variable aber erzwingen.

Weitere System-Variablen: MSG_CALL_HEADER_HTTP_METHOD, MSG_CALL_HEADER_HTTP_PROTOCOL, MSG_CALL_HEADER_HTTP_REMOTE_HOST, MSG_CALL_HEADER_HTTP_URI, MSG_CALL_HTTP_AUTH_USER, MSG_CALL_HEADER_HTTP_QUERY.

Response-Ablauf

Konnte kein Profil gefunden werden, oder die Pflicht-Parameter passen nicht, bekommen Sie eine entsprechende Meldung zurück.

Wurde ein passendes Profil gefunden, erfolgt die Response, wenn das Profil erfolgreich beendet wurde oder ein Fehler aufgetreten ist. Ist (6) gesetzt, erfolgt die Response aber sofort.

Der Inhalt der Response ist festgelegt durch die Einstellungen in (13).

Hinweis: Abschnitt gilt nicht, wenn ein Fehler im Zusammenhang mit der HTTP-Methode (4) auftrat. Siehe Abschnitt "Request-Body, Profil-Verhalten und Profil-Eingangsdaten".

Response-Header

Ist (13) gesetzt und sind System-Variablen der Form VAR_RESPONSE_HTTP_HEADER_<Name des Response-Headers> angelegt, dann werden entsprechende Response-Header mit den Werten der Variablen gesetzt. Beispiel: Die Variable "VAR_RESPONSE_HTTP_HEADER_Test" mit dem Initialwert "mytest" erzeugt den HTTP-Response-Header "Test" mit dem Wert "mytest". Hinweis: Der Response-Header "Content-Length" wird ignoriert, d. h. er kann nicht überschrieben werden.

Hinweis: Abschnitt gilt nicht, wenn ein Fehler im Zusammenhang mit der HTTP-Methode (4) auftrat. Siehe Abschnitt "Request-Body, Profil-Verhalten und Profil-Eingangsdaten".

Response-Status

Wurde das Profil erfolgreich ausgeführt, ist der Response Status "200". Wenn in (13) "Eigene Klasse..." gesetzt ist, kann der Response Status "200" auch überschrieben werden mit der System-Variable VAR_RESPONSE_HTTP_HEADER_RESP_STATUS. Wird in (13) "Kein Rückgabewert" gesetzt, ist der Response Status "204".

Trat während der Profil-Ausführung ein Fehler auf, ist der Response Status der Wert, der in (16) festgelegt wurde, bzw. wie er von der Funktion throw http exception(a,b) gesetzt wurde.

Ist (6) gesetzt, ist der Response Status "200", sobald das Profil erfolgreich angestoßen wurde. Die Funktion "throw http exception(a,b)" kann dann den Response Status nicht verändern.

Hinweis: Abschnitt gilt nicht, wenn ein Fehler im Zusammenhang mit der HTTP-Methode (4) auftrat. Siehe Abschnitt "Request-Body, Profil-Verhalten und Profil-Eingangsdaten".

HTTP-Multipart-Nachrichten handhaben

Der Eingangsagent selbst nimmt immer nur den ersten Multipart entgegen, siehe (11). Die weiteren Parts gehen aber nicht verloren und werden intern in System-Variablen gespeichert.

Der Name des zweiten Parts würde z. B. in der Variable MSG_CALL_HTTP_MULTIPART1_NAME gespeichert und dessen Wert in MSG_CALL_HTTP_MULTIPART1_VALUE. Der dritte Part dann in "MSG_CALL_HTTP_MULTIPART2_NAME" und "MSG_CALL_HTTP_MULTIPART2_VALUE", usw. Die Gesamtzahl aller Parts, einschließlich des Haupt-Parts aus (11), wird in System-Variable MSG_CALL_HTTP_MULTIPARTS gespeichert.

Im Idealfall wissen Sie, wie viele Parts kommen werden und legen die benötigten Variablen im Profil an. Sollte dies einmal nicht möglich sein, kann man sich mit einem kleinen Trick behelfen, der es unnötig macht, die Variablen davor anzulegen und es ermöglicht diese sozusagen dynamisch auszulesen. Sie verwenden dazu schlicht die System-Variable MSG_CALL_HTTP_MULTIPARTS (diese können Sie natürlich davor anlegen), um herauszufinden, wie viele Parts gekommen sind. Mit diesem Wert iterieren Sie dann einen Knoten und lesen die jeweiligen Variablenwerte mit der Funktion "copy field by name(variable/result a)" aus (verwenden Sie dazu den Typ "Wert" für Parameter a). Den Namen der jeweiligen Variable können Sie über die Funktionen "iteration-level" und "concat(a,b,c,d,e,f,g,h, [CR-support i])" erzeugen. Vergessen Sie bitte nicht, dass die Variable MSG_CALL_HTTP_MULTIPARTS die Anzahl aller Parts angibt. Über die Variablen können Sie aber nur ab dem zweiten Part auslesen.