HTTP-Anfrage (REST Call, API Call)

Ereignisaktion - Kurzfassung
Zweck: Die Ereignisaktion führt eine HTTP-Abfrage mit einer unterstützten Methode (GET, POST, PUT, PATCH, DELETE) aus und gewährt Zugriff auf die Antwort.
Tooltip
Verwendung: Die Ereignisaktion merkt Inhalt zum Erzeugen eines Log-Eintrags beim Abschluss der aktuellen Transaktion vor.
Parameter:
Die auszuführende Methode muss unterstützt (GET, POST, PUT, PATCH, DELETE) und in Großbuchstaben angegeben sein, sonst wird GET verwendet.
URL und ggf. Query definieren die betreffenden Komponenten der "Aufrufadresse".
Anfrage-Header und Payload definieren Daten, die der Anfrage mitgegeben werden.
Header der Antwort und Inhalt der Antwort definieren Ziele für Zuweisungen von Details aus der Antwort.
Weitere Parameter sind in einem Aufklappbar (Expandable)-Element "versteckt":
Für die Authentifizierung der Anfrage können Referenzen auf eine serverseitig hinterlegte HTTP Kanal-ID oder eine Zertifikats-ID genutzt werden.
Die Option Streaming verwenden ermöglicht die Reaktion auf "gepushte" Server-sent Events via Antwort-Typ text/event-stream.
Mit der Option Via DMZ wird die Anfrage über die DMZ ausgeführt.
Der Timeout bestimmt (außer bei Streaming verwenden), nach welcher maximalen Wartezeit in Sekunden die Anfrage kontrolliert abgebrochen werden soll.
Die Einstellung Anzahl Neuversuche wird der Anfrage mitgegeben, damit ggf. Wiederholungsläufe ausgelöst werden.
Hinweis: Das via Header der Antwort zugewiesene "Speicher" (Storage)-Objekt, weist über den Schlüssel RESPONSE_CODE den Verlaufsstatus der Anfrage aus. Der optionale Schlüssel ERROR_INFO beinhaltet ggf. weiterführende Fehlerinformationen.

images/download/attachments/189457412/image-2025-1-8_9-1-52-version-1-modificationdate-1736323312428-api-v2.png

Die HTTP-Anfrage (REST Call, API Call)-Ereignisaktion führt eine HTTP-Anfrage für eine unterstützte Methode (GET , POST , PUT,PATCH, DELETE) unter Berücksichtigung der weiteren konfigurierten Parameter (Details s. "Konfiguration") aus.

Die URL muss ein Protokoll (z. B. https) und eine für den Lobster Data Platform-Server auflösbare Web-Adresse beinhalten.
- Die Parameter URL und Query befinden sich im Kopfbereich eines Aufklappbar (Expandable)-Elements, dessen Detailbereich (im Screenshot oben aufgeklappt dargestellt) weitere Parameter enthält (Details s. "Konfiguration").
Die Angabe einer Zeichenfolge für den Parameter Query ist technisch optional. Sie ermöglicht Wertzuweisungen an URL-Parameter die gemäß der Syntax der Methode berücksichtigt werden.
Die Parameter Anfrage-Header und Payload definieren den Header und die ggf. zu übertragende "Nutzlast" (en.: payload) für die Anfrage (Details s. "Konfiguration").

Sofern der URL überhaupt aufgelöst werden kann und der adressierte Server reagiert, wird die Antwort (en.: Response) wie folgt aufbereitet:

Aus Header-Informationen wird ein Datenobjekt des Typs "Speicher" (Storage) erzeugt, das per Standard (s. Parameter Header der Antwort) in die Variable httpResponseHeaders gespeichert wird.
Aus dem abhängig von der gewählten Methode ggf. bereitgestellten Body wird ein Datenobjekt des Typs "Inhalt" (Content) erzeugt, das per Standard (s. Parameter Inhalt der Antwort) in die Variable httpResponseContent gespeichert wird.

Konfiguration

Die Ereignisaktion HTTP-Anfrage (REST Call, API Call) erwartet kein spezifisches Bezugsobjekt. Allerdings können Wert-Konfigurationen für Parameter auf das ggf. anwendbare Bezugsobjekt zugreifen.

Sämtliche Parameter können bei Bedarf durch Wert-Konfigurationen definiert werden. Falls ein statischer Wert konfiguriert ist (s. Statische Werte) und das betreffende Formularelement in Verbindung mit einem kleinen grauen Pfeil (links unten) angezeigt wird, muss dieser angeklickt werden, um zur Wert-Konfiguration umzuschalten.

Parameter	Datentyp	Standardwert	Verwendung
Methode	Text (`String`)	`GET`	Der wahlweise per Direkteingabe oder über eine Wert-Konfiguration zur Laufzeit dynamisch ermittelte Textwert für die Methode muss exakt dem Namen einer der unterstützten HTTP Methods entsprechen. Die Ereignisaktion unterstützt ausschließlich die HTTP Methods in der folgenden Positivliste: `GET` ... fordert Daten für eine per URL und ggf. Query spezifizierte Ressource an. `POST` ... sendet die Payload-Daten an die URL und ggf. Query spezifizierte Ressource. `PUT` ... sendet Payload-Daten, mit denen die per URL und ggf. Query spezifizierte Ressource erstellt oder aktualisiert werden soll. `PATCH` ... sendet Payload-Daten, mit denen Eigenschaften der per URL und ggf. Query spezifizierte Ressource aktualisiert werden sollen. `DELETE` ... löscht die per URL und ggf. Query spezifizierte Ressource. Diese Positivliste könnte in zukünftigen Versionen erweitert werden. ►WICHTIG◄ Eine ungeeignete Eingabe/Konfiguration für den Parameter "Methode" erzeugt in vielen Fällen keine Fehlermeldung, weil `GET` *als Fallback* ausgeführt wird. Folgende Regeln gelten für die Interpretation von Textwerten für den Parameter Methode: Der Textwert wird nicht getrimmt Der Textwert wird und unter Berücksichtigung der Groß-/Kleinschreibung mit der Positivliste abgeglichen, die ausschließlich Großbuchstaben verwendet. Liefert der Abgleich mit der Positivliste keinen Treffer, dann wird auf den Standardwert `GET` als Methode zurückgegriffen. Die folgenden Beispiele demonstrieren mögliche Auswirkungen: Wird bei der Direkteingabe der Methode versehentlich ein Leerzeichen angehängt (z. B. "`POST` " statt "`POST`"), erfolgt ein `GET`-Aufruf mit den Parametern URL und ggf. Query aber ohne Payload. Beim Versuch die `POST`-Methode mit abweichender Groß-/Kleinschreibung per `Post` zu adressieren, wird stattdessen ein `GET`-Aufruf (ohne Payload) ausgeführt. Beim Versuch eine korrekt adressierte aber von der Ereignisaktion nicht unterstützte Methode (z. B. `HEAD`) auszuführen, erfolgt stattdessen ein `GET`-Aufruf. Falls die per URL und ggf. Query** adressierte Ressource `GET`-Aufrufe unterstützt, erhält man eine ggf. sehr umfangreiche Antwort, was man mit der `HEAD`-Methode typischerweise genau vermeiden will. Ob die adressierte Ressource die `HEAD`-Methode überhaupt unterstützt, spielt dagegen keine Rolle. Sie wird auch nicht ausgeführt. "Kein Wert" (`$null`) oder eine leere Zeichenfolge (`""`) liefert, ist die Ereignisaktion nicht etwa wirkungslos. Vielmehr wird ebenfalls ein `GET`-Aufruf ausgeführt.
URL	Text (`String`)	Kein Wert	Der wahlweise per Direkteingabe oder über eine Wert-Konfiguration zur Laufzeit dynamisch ermittelte Textwert für die URL muss das zu verwendete Protokoll (z. B. `http` oder `https`) benennen, bevor der Pfad in der anwendbaren Syntax nachfolgt. ►HINWEIS◄ Falls die HTTP-Anfrage URL-Parameter verwenden soll, muss der komplette HTTP Query String per Parameter Query definiert sein. Beinhaltet die Zeichenfolge für die URL einen HTTP Query String, wird dieser ignoriert.
Query	Text (`String`)	Kein Wert	Optional kann im Parameter Query ein wahlweise per Direkteingabe oder über eine Wert-Konfiguration zur Laufzeit dynamisch ermittelter Textwert bereitgestellt werden, der als HTTP Query String and die als URL definierte Zeichenfolge angehängt wird. Das in der URL Syntax vorgesehene Trennzeichen (`?`) wird dabei automatisch eingefügt. Es sollte also weder in der URL-Zeichenfolge noch in der Query-Zeichenfolge enthalten sein. Die Query-Zeichenfolge kann mehrere Wertzuweisungen mit dem Schema `<key>=<value>` über das Trennzeichen `&` verketten. Beispiel: Die folgende Query-Zeichenfolge enthält Zuweisungen für drei Parameter: token=DEMO&region=APAC&fromDate=2025-01-01
Anfrage-Header	Speicher(`Storage`)	Kein Wert	Die optionale Wert-Konfiguration für den Parameter Anfrage-Header sollte zur Laufzeit ein "Speicher" (`Storage`)-Datenobjekt zurückgeben, das die Informationen für den HTTP Request Header beinhaltet.►HINWEIS◄ Anstelle eines "Speicher" (`Storage`)-Datenobjekts können auch die Objekttypen "Map" (`Map`) oder "Client-Objekt" (`ASObject`) verwendet werden, um Header-Informationen bereitzustellen.
Payload	Inhalt(`Content`)	Kein Wert	Die Wert-Konfiguration für den Parameter Payload sollte zur Laufzeit ein "Inhalt" (`Content`)-Datenobjekt zurückgeben, dessen `body`-Feld die eigentliche "Nutzlast" (en.: payload) für den HTTP Request beinhaltet.►HINWEIS◄ Rein technisch ist die Wert-Konfiguration für die Payload optional. Allerdings kann die Payload abhängig von der Methode (s. o.) erforderlich sein. Fall der Anfrage-Header keine explizite Zuweisung für den Schlüssel `Content-Type` enthält, wird als Fallback das `mediaType`-Feld des als Payload definierten "Inhalt"-Objekts übernommen. Falls der `Content-Type` weder per Anfrage-Header noch per Payload definiert ist, wird im `Content-Type`-Header der Standardwert `application-octet-stream` zugewiesen. ►WICHTIG◄ Falls die Wert-Konfiguration für den Parameter Payload einen anderen Typ als "Inhalt" (`Content`) liefert, wird versucht den Rückgabewert in diesen Typ umzuwandeln. Dies gelingt z. B. ausgehend von einem `String`-Wert. Ist der Rückgabewert dagegen nicht in "Inhalt" (`Content`) umwandelbar, dann wird versucht die Methode ohne Payload auszuführen. Das verursacht ggf. Fehler.
Header der Antwort	Speicher(`Storage`)	Variable`httpResponseHeaders`	Die optionale Wert-Konfiguration für den Parameter Header der Antwort definiert das Ziel einer Wertzuweisung für das die zur Laufzeit generierte "Speicher" (`Storage`)-Datenobjekt, dessen Felder die Header-Informationen aus dem HTTP Response wiedergeben. Auf diesem Weg können die Header der Antwort nach dem Ausführen der HTTP-Anfrage (REST Call, API Call)-Ereignisaktion ausgewertet werden. ►WICHTIG◄ Das als Header der Antwort erzeugte "Speicher" (`Storage`)-Objekt enthält typischerweise den `RESPONSE_CODE`, aus dem erkennbar ist, ob der HTTP Request erfolgreich oder mit Fehlern abgearbeitet wurde. Die Header der Antwort können im Fehlerfall bei Bedarf weiterführend untersucht werden. Per Standard ist ein Variable-Wertauflöser konfiguriert, der den Variablennamen `httpResponseHeaders` mit dem Typ "Speicher" (`Storage`) verknüpft.►HINWEIS◄ Falls die `httpResponseHeaders`-Variable vor dem Ausführen der HTTP-Anfrage (REST Call, API Call)-Ereignisaktion bereits einen Wert enthält, wird dieser durch die Zuweisung überschrieben. Anstelle der vorkonfigurierten Variablen kann ein beliebiges anderes geeignetes Ziel für eine Zuweisung - z. B. eine andere Variable, ein Objekt-Feld oder eine Dateireferenz - konfiguriert werden. Falls keine oder eine als Ziel für eine Zuweisung ungeeignete Wert-Konfiguration vorliegt, kann nach dem Ausführen der HTTP-Anfrage (REST Call, API Call)-Ereignisaktion nicht auf die Header der Antwort zugegriffen werden.
Inhalt der Antwort	Inhalt(`Content`)	Kein Wert	Die optionale Wert-Konfiguration für den Parameter Inhalt der Antwort definiert das Ziel einer Wertzuweisung für das zur Laufzeit generierte "Inhalt" (`Content`)-Datenobjekt das die "Nutzlast" der Antwort abbildet. Das `body`-Feld enthält die eigentlichen Nutzdaten als Byte Array (`byte[]`). Der Wert im `mediaType`-Feld gibt den Wert für den Response Header `Content-Type` aus dem Header der Antwort wieder. ►HINWEIS◄ Falls die Inhalt anzeigen-Ereignisaktion verwendet wird, um das "Inhalt"-Objekt aus dem Rückgabewert anzuzeigen, kann der Wert im `mediaType`-Feld bei Bedarf überschrieben werden, um die Behandlung den Inhalts durch den Browser zu beeinflussen.
Die folgenden Parameter sind im Detailbereich eines Aufklappbar (Expandable)-Elements enthalten, das per Standard zugeklappt ist.
HTTP Kanal-ID	Ganzzahl(`Long`)	Kein Wert	Über den Parameter HTTP Kanal-ID kann eine Referenz auf einen in angelegten Kanal (s. Lobster Data Platform / Integration, "Kanäle") erfolgen. Liegt eine Wert-Konfiguration vor, die zur Laufzeit eine valide HTTP Kanal-ID (`Long`-Wert) verweist, werden die dort hinterlegten Angaben (s. Lobster Data Platform / Integration, "Eigener Zugang (Ich zum Partner)") für die Authentifizierung des HTTP Requests herangezogen: Der Wert des Felds "Eigene Kennung" für den referenzierten Kanal wird als Benutzerkennung verwendet. Das Wert des Feld "Eigenes Kennwort" für den referenzierten Kanal wird als Passwort verwendet.
Zertifikats-ID	Ganzzahl(`Long`)	Kein Wert	Falls die Authentifizierung des HTTP Requests ein serverseitig hinterlegtes Eigenes Zertifikat (s. Lobster Data Platform / Integration, "Eigene Zertifikate") erfordert, kann dieses über den Parameter Zertifikats-ID referenziert werden, indem eine Wert-Konfiguration einrichtet wird, die zur Laufzeit einer `Long`-Wert liefert, der mit der internen ID des betreffenden Zertifikats übereinstimmt.
Streaming verwenden	Boolescher Wert(`Boolean`)	Kein Wert	Die Option Streaming verwenden muss ausgewählt werden, damit als Antwort auf eine Anfrage bereitgestellte Server-sent Events (SSE) einzeln abgearbeitet werden können (s. Server-sent Events (SSE) verarbeiten). Der Medientyp (`mediaType`) für den Inhalt der Antwort ist immer `text/event-stream`. Der Stream (en.: Strom) von SSEs (Server-sent Events) kann nach dem Ausführen der HTTP-Anfrage (REST Call, API Call) verarbeitet werden, indem die Variable `httpResponseContent` im Kopf einer Schleife gelesen wird. Jede Iteration der Schleife bezieht sich dann auf genau eines der Events als Bezugsobjekt. Die Option Streaming verwenden hat dabei folgenden Einfluss: Ist die Option Streaming verwenden ausgewählt, dann wartet die Schleife bis der Server ein Event sendet, verarbeitet es und wartet danach auf das nächste, bis der Server die Verbindung beendet. Ist die Option Streaming verwenden abgewählt, dann startet die Schleife erst, wenn der Server die Verbindung beendet hat und verarbeitet dann alle empfangenen Events.
Via DMZ	Boolescher Wert(`Boolean`)	Kein Wert	Ist die Option Via DMZ ausgewählt, wird der HTTP Request über die DMZ ausgeführt. Der Auswahl der Option kann wahlweise über das Checkbox-Element in der Konfiguration statisch definiert oder an eine Wert-Konfiguration gebunden werden, die zur Laufzeit einen Booleschen Wert (`Boolean`) liefert.
Timeout	Ganzzahl(`Integer`)	90	Der Parameter Timeout definiert eine Obergrenze für die Laufzeit des HTTP Requests in Sekunden. Per Standard ist ein Wert von 90 (Sekunden) zugeordnet. Überschreitet die Laufzeit eines HTTP Requests die per Timeout definierte Grenze, wird die Ausführung abgebrochen. Die Ereignisbehandlung wird allerdings nicht abgebrochen, sodass anschließend das per Header der Antwort erzeugte "Speicher" (`Storage`)-Datenobjekt ausgewertet werden kann, um festzustellen, ob ein Timeout stattgefunden hat. Der Schlüssel `ERROR_INFO` enthält in diesem Fall ein "Fehlerinformation" (`ErrorInfo`)-Datenobjekt dessen `errorText`-Feld den Textwert "`Read timed out`" enthält.
Anzahl Neuversuche	Ganzzahl(`Integer`)	0	Der Parameter Anzahl Neuversuche definiert die Anzahl der Wiederholungsläufe, die ausgeführt werden, falls der HTTP Request keine Antwort mit einem `RESPONSE_CODE` im Header liefert. Per Standard ist der Wert 0 zugeordnet. Mit dieser Einstellung erfolgen keine Wiederholungsläufe.