HTTP (Eingangsagent)
Einführung: Phase 1 und HTTP und Lobster_data.
Basis-URL: http(s)://<URL oder IP des Integration Servers>/dw/Request (Details in Punkt 1 unten).
(1) Der URL-Suffix. Die URL für dieses Profil ist dann http(s)://<URL oder IP des Integration Servers>/dw/Request/example. Siehe mehr Details in Abschnitt HTTP-Adresse von Lobster_data.
(2) Die erlaubten HTTP-Methoden. Hinweis: Siehe auch die System-Variablen MSG_CALL_HEADER_HTTP_(...).
(3) Der Eingangsagent fungiert als REST-Schnittstelle. D. h., ist die URL des Eingangsagenten wie hier z. B. http://localhost/dw/Request/example, dann würde auch ein Request http://localhost/dw/Request/example/orders angenommen werden. Der zusätzliche Request-Suffix /orders wird dann in der System-Variable MSG_CALL_HTTP_PATH_DATA gespeichert. Ansonsten verhält sich der Eingangsagent wie bei einem "normalen" Request.
(4) Erlaubt dem Profil als Webservice zu agieren. Siehe dazu die Abschnitte Profil als Webservice betreiben (ohne Rückmeldung) und Profil als Webservice betreiben (mit Rückmeldung).
(5) Content-Type der Antwort.
(6) 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 unten.
(7) Ein leerer HTTP-Body wird nicht als Fehler gesehen.
(8) und (9) Die Antwort im Erfolgsfall kann auf zwei verschiedene Arten gesendet werden:
Durch festen Wert (9): Es soll hier eine statische Antwort gesendet werden.
Alternativ kann die Antwort dynamisch durch eine eigene Klasse im Antwortweg (8) erzeugt werden oder durch die Option Daten zurückliefern in den Antwortwegen HTTP und Message. Siehe hierzu speziell Abschnitt HTTP-Response-Kette.
Wichtiger Hinweis: Mit der System-Variable VAR_RESPONSE_HTTP_HEADER_RESP_STATUS kann der HTTP-Response-Status gesetzt werden. Bei gesetzter Option (8) wird diese Variable ausgewertet und der HTTP-Response-Status von der Klasse gesetzt. Siehe allgemein auch VAR_RESPONSE_HTTP_HEADER_<Name des Response-Headers>.
(10) Antwort, die im Fehlerfall gesendet wird. Hinweis: Es kann hier auch der Platzhalter {--Exception--} verwendet werden. Tritt im Job ein Fehler in Phasen 2-6 auf und 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.
(11) Der HTTP-Status-Code, der im Fehlerfall zurückgeschickt wird.
(12) Entweder ohne Zugangskontrolle oder mit Zugangskontrolle über einen oder mehrere ausgewählte HTTP-Kanäle oder mit direkt angegebenen Zugangsdaten. Siehe auch System-Variable MSG_CALL_HTTP_AUTH_USER.
(13) Festlegung der Request-Parameter. Zum Zugriff auf die Parameter im Profil über Variablen siehe Abschnitt HTTP-Request-Parameter und HTTP-Header.
Hinweis: Die System-Variable MSG_CALL_HEADER_HTTP_METHOD wird gefüllt mit der Methode des HTTP-Requests (z. B. GET, POST, ...), um dem Profil das Erkennen der Aufrufmethode zu ermöglichen. Das HTTP-Servlet, das den Request an das Profil weiterleitet, wird beim Start von Lobster_data automatisch gestartet und reagiert per Default auf den HTTP-Kontext /dw/Request bzw. /dw/request. Die nachfolgende Komponente /<suffix> in der URL ergibt sich aus dem URL-Adressen-Suffix (1). Das Servlet sucht zunächst das korrekte Profil zum eingegangenen Request. Dabei werden alle Profile durchsucht, die einen HTTP-Eingangsagent haben und deren URL mit dem Wert aus (1) endet.
Zusätzlich müssen die HTTP(S)-Request-Parameter zur HTTP(S)-Request-Parameter-Festlegung (13) passen. Das erste zutreffende Profil wird vom Servlet ausgewählt und die Verarbeitung angestoßenen. Falls weitere Profile die Bedingungen erfüllen, werden diese Profile nicht berücksichtigt.
Beispiel: HTTP-Requests mit der folgenden URL führen zu einem Aufruf des Profils mit dem Eingangsagenten oben und folgender Request-Parameter-Konfiguration.
|
http://<host>[:<port >]/dw/Request/example?param1=value1¶m2=value2¶m3=value3¶m4=value4 |
Dabei bezeichnet host den DNS-Namen oder die IP-Adresse des Rechners, auf dem Lobster_data (bzw. der Integration Server) läuft und port den Port, an dem der HTTP(S)-Service von Lobster_data hört.
Hinweis: Bitte beachten Sie auch den Abschnitt URL-Context systemweit definieren.
HTTP-Multipart-Nachrichten handhaben
Der Eingangsagent selbst nimmt immer nur den ersten Multipart entgegen, siehe (6). 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 der Parts, einschließlich des Haupt-Parts aus (6), wird in System-Variable MSG_CALL_HTTP_MULTIPARTS gespeichert.
Hinweis: 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) erzeugen. Hinweis: 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.