Dieser Eingangsagent ruft zeitgesteuert Daten von einem HTTP(S)-Server ab. Er sendet eine HTTP-Anfrage und verarbeitet die Antwort als Eingangsdaten. Die Anfrage konfigurieren Sie manuell oder erzeugen sie aus einer Swagger- beziehungsweise OpenAPI-Definition.
Einstellungen
.png)
① Swagger Import: Die Vorlagen erhalten Sie im Update-Center. Rechts daneben laden Sie eine Swagger-Datei hoch, direkt oder per URL. Der Eingangsagent setzt dabei HTTP-Methode, URL und Content-Type automatisch. Bei Bedarf legt er außerdem eine passende Quellstruktur an, inklusive Zielstruktur per 1:1-Mapping. Enthält der Pfad eine URL-Variable, legt der Eingangsagent passende MSG_CALL_-Variablen im Profil an. Er fügt sie zusätzlich in die URL ein. Siehe Abschnitt Profil per HTTP triggern. Beispiel: https://petstore3.swagger.io/api/v3/openapi.json mit dem Pfad [GET] /pet/{petId}.
Swagger-Import-Dialog
Der Dialog für den Swagger-Import hat eine eigene Nummerierung.
① Endpoint: Geben Sie die URL an, oder laden Sie eine Datei hoch. Beispiel: https://petstore3.swagger.io/api/v3/openapi.json.
② Anfragen: Ruft die Swagger- oder OpenAPI-Definition von der angegebenen URL ab.
③ Path: Wählen Sie den gewünschten Pfad aus.
④ Anwenden: Übernimmt den gewählten Pfad und die zugehörigen Einstellungen in den Eingangsagenten.
Weitere Details finden Sie im Abschnitt Designer (Data Flow) unter Swagger import.
Weitere Einstellungen
② API-Protokoll: Aktivieren Sie die Option Ist eine SOAP-WS-Anfrage nur beim Aufruf eines SOAP-Webservice. Dabei erscheinen zusätzliche Buttons unter dem Datenfeld. Siehe Abschnitt Mit Profil SOAP-Webservice aufrufen im Eingangsagenten.
③ HTTP-Methode: Legt die zu verwendende HTTP-Methode fest. Erlaubt sind GET, GET (with content), POST, PUT, PATCH, DELETE, DELETE (with content) und HEAD.
④ URL: Geben Sie die URL (mit Port) des entfernten HTTP(S)-Servers an. HINWEIS: Das Feld kodiert die URL nicht. Für eine automatische Kodierung setzen Sie die Checkbox in ⑥.
Für das Feld gelten außerdem diese Regeln:
Wählen Sie einen Kanal aus ⑭, dann ersetzt der Eingangsagent den Platzhalter
<serverurl>. Er verwendet dafür den Wert des Kanal-Feldes Partner-Adresse.Sie können den Platzhalter
{--0:s#<template>--}für den Zeitstempel des letzten Laufs des Profils verwenden. Beispiel:http://example.com?time={--0:s#yyyyMMdd--}. Der Eingangsagent aktualisiert den Zeitstempel nur, wenn Sie den Platzhalter in der URL oder in ⑬ tatsächlich verwenden. Zudem muss der HTTP-Response-Status-Code im Bereich 200 bis 299 liegen. Siehe auch Abschnitt Paging/Pagination.Erlaubt sind Variablen (Syntax
@MSG_CALL_MYVAR@), Systemkonstanten (Syntax%MYCONST%) und permanente Profil-Werte (Syntax%perm:KEYNAME%). Ein Auswahlmenü zeigt die verfügbaren Werte.
⑤ Via DMZ: Aktivieren Sie diese Option, damit der Eingangsagent die Anfrage über den DMZ-Server sendet. Ohne DMZ-Server läuft die Anfrage über den internen Integration Server. Die Option gilt auch für den OAuth-Token-Refresh. Voraussetzung dafür ist ein Kanal ⑭ mit konfiguriertem OAuth.
⑥ URL automatisch encoden: Ist die Checkbox gesetzt, kodiert der Eingangsagent den Wert aus ④ automatisch als URL.
⑦ Timeout: Legt den Timeout für die HTTP-Verbindung fest.
⑧ HTTP-Header anpassen: Hier fügen Sie zusätzliche HTTP-Request-Header ein. Siehe Abschnitt Request-Header. Verwenden Sie einen Kanal, dann definieren Sie Header auch dort in den Zusatzkennungen. Für Header-Name und Header-Wert können Sie Variablen einsetzen (Syntax @MSG_CALL_MYVAR@). Für den Wert sind zusätzlich Systemkonstanten (Syntax %MYCONST%) und permanente Profil-Werte (Syntax %perm:KEYNAME%) erlaubt. Ein Auswahlmenü zeigt die verfügbaren Werte.
⑨ Anfragen & Struktur erzeugen: Führt eine Anfrage aus und öffnet den Datei-Struktur-Analyse-Dialog für die Antwort. Daraus erzeugen Sie eine passende Quellstruktur. Nutzen Sie diese Funktion auch, wenn Sie in ② SOAP eingestellt haben und die Gegenstelle keine WSDL liefert.
⑩ Multipart/form-data: Erzeugt einen Multipart-Request. Sie fügen Parts oder Datei-Parts ein. Siehe Abschnitt Multipart.
⑪ Content-Type: Legt den MIME-Type für den Header Content-Type fest. Standardmäßig ergänzt der Eingangsagent dort auch das Encoding aus den Basis-Daten, zum Beispiel application/octet-stream;charset=ISO-8859-1. Um das zu verhindern, tragen Sie stattdessen den Wert application/octet-stream;raw ein. Der Eingangsagent verwendet dann nur application/octet-stream als Content-Type. Entfernen Sie den Haken in ⑫, dann trägt der Eingangsagent diesen Wert automatisch ein.
⑫ Encoding zum Content-Type hinzufügen: Steuert, ob der Eingangsagent das Encoding an den Content-Type anhängt. Details siehe ⑪.
⑬ Daten: Enthält die Body-Daten. Das Feld ist bei den HTTP-Methoden HEAD, GET und DELETE nicht verfügbar, siehe ③. Ebenso fehlt es, wenn Sie ⑩ nutzen.
Für das Feld gelten außerdem diese Regeln:
Sie können Systemkonstanten in der Form
%MYCONSTANT%verwenden. Enthält die Systemkonstante einen Datums-Platzhalter, zum Beispiel<yyyy>-<MM>-<dd>, dann gibt der Eingangsagent das aktuelle Datum in diesem Format aus.Sie können den Platzhalter
{--0:s#<template>--}für den Zeitstempel des letzten Laufs des Profils verwenden. Beispiel:{--0:s#yyyyMMdd--}. Der Eingangsagent aktualisiert den Zeitstempel nur, wenn Sie den Platzhalter in den Daten oder in ④ tatsächlich verwenden. Zudem muss der HTTP-Response-Status-Code im Bereich 200 bis 299 liegen.Erlaubt sind MSG_CALL_-Variablen.
⑭ Kanal-Auswahl: Wählen Sie hier einen Kanal vom Typ HTTP aus. Der Eingangsagent verwendet dann in ⑯ die Authentifizierungsdaten aus dem Kanal. Er nutzt dafür die Felder Eigene Kennung und Eigenes Kennwort.
⑮ Zertifikats-Auswahl: Ist ④ eine HTTPS-URL, dann können Sie optional ein Client-Zertifikat zuordnen. Wählen Sie dazu eines der hinterlegten Zertifikate aus.
⑯ Benutzer, Kennwort: Hinterlegen Sie hier optional Authentifizierungsdaten. Für Vault-Passwörter siehe Abschnitt Vault provider configuration.
Sie können auch MSG_CALL_-Variablen verwenden. Alternativ verwenden Sie die Authentifizierungsdaten eines ausgewählten Kanals, siehe ⑭.
MS-IIS mit NTLM-Authentifizierung: Manche HTTP-Server erwarten eine integrierte Windows-Authentifizierung vom Typ NTLM Version 1 oder 2. Stellen Sie dem Benutzernamen dann einen Domänennamen voran. Verwenden Sie im Feld für den Benutzernamen die Syntax domain\\user mit doppeltem Backslash.
⑰ Auch bei HTTP-Status ungleich 2xx fortfahren: Ist diese Checkbox gesetzt, brechen HTTP-Status-Codes außerhalb von 2xx das Profil nicht ab. So implementieren Sie eine eigene Fehlerbehandlung. Siehe Abschnitt Response und Response-Header. HINWEIS: Schlägt die Anfrage vollständig fehl, greift die Option nicht. Das passiert zum Beispiel, wenn der Server nicht erreichbar ist. Erhält das Profil keine Daten, dann entsteht kein Job.
⑱ Parallelverarbeitung aktivieren: Ist diese Checkbox gesetzt, arbeiten mehrere Instanzen dieses Profils parallel. Die Checkbox Profil darf nur in einer Instanz laufen darf für dieses Profil dann nicht gesetzt sein. Bei aktivierter Option arbeitet der Eingangsagent die Jobs dieses Profils in einer Thread Queue ab.
⑲ Paging aktivieren: Aktiviert den Abruf in mehreren Teildatensätzen. Details siehe Abschnitt Paging/Pagination.
⑳ Validiere Zertifikatskette des Servers: Ist diese Option aktiviert, prüft der Eingangsagent das Serverzertifikat anhand des internen JVM-Truststores. Der Truststore ist ein Repository vertrauenswürdiger SSL-Zertifikate.
Multipart
Multipart mode | Erlaubte Werte: Header: Der Multipart Mode bei |
HTTP-Methode | Der Multipart-Modus unterstützt nur die HTTP-Methoden |
Ist Datei | Ohne Häkchen fügt der Eingangsagent einen Part ein, mit Häkchen einen Datei-Part. |
Schlüssel | Erforderlich. Wählen Sie einen beliebigen, aber eindeutigen Schlüssel. |
Wert/Dateipfad | Der Eingangsagent fügt den Inhalt der Spalte Wert/Dateipfad als Part ein. Setzen Sie die Checkbox Ist Datei, dann fügt er ihn als Datei-Part ein. Verwenden Sie in der Spalte das Präfix |
Dateiname | Optional. Verwenden Sie das Präfix |
Content-Type | Erforderlich. Standardmäßig ergänzt der Eingangsagent im Content-Type auch das Encoding, zum Beispiel Im Header |
Encoding | Optional. Bei Parts verwendet der Eingangsagent standardmäßig |
Request-Header
Zusätzliche Request-Header fügen Sie über ⑧ ein. Verwenden Sie einen Kanal ⑭, dann setzen Sie Request-Header auch dort. Siehe Abschnitt Zusatzkennungen (im Kanal). Setzen Sie einen gleichnamigen Header an beiden Stellen, dann hat der Header aus dem Profil Vorrang.
Cookies schreiben Sie über den Header Set-Cookie.
Response und Response-Header
Das Profil setzt die Ausführung bei allen Response-Status-Codes 2xx fort. Bei anderen Status-Codes entsteht ein Fehler. Die Checkbox ⑰ ändert dieses Verhalten.
Response-Header lesen Sie über die System-Variablen MSG_CALL_VAR_HTTP_<Name des Headers in Großbuchstaben> aus. Siehe auch MSG_CALL_VAR_HTTP_STATUS_CODE und MSG_CALL_VAR_HTTP_STATUS_LINE.
Raw Request/Response
Aktivieren Sie die Trace-Meldungen für Phase 1 in der Logging-Konfiguration. So sehen Sie zu Testzwecken den Raw Request und die Raw Response samt Headern. Das ist besonders bei der HTTP-Methode POST mit Multipart hilfreich. Sie finden diese Daten auf der Seite Allgemeine Meldungen im Control Center als Base64-codierten String. Dekodieren Sie den String mit dem Plugin Encode/Decode. Alternativ verwenden Sie externe Tools wie requestcatcher.com.
Paging/Pagination
Paging (oder Pagination) bezeichnet den Abruf sehr großer Datensätze einer REST API in mehreren Teildatensätzen.
So setzen Sie Paging um:
Erstellen Sie ein Profil mit diesem Eingangsagenten. Tragen Sie die erste URL ein. Diese URL hängt von der verwendeten REST API ab, zum Beispiel
https://example.com/users?limit=100&page=1.Setzen Sie die Checkbox Paging aktivieren ⑲.
Legen Sie die Variable
VAR_SYS_HTTP_PAGING_URLan.Füllen Sie die Variable im Mapping mit der URL für den nächsten Teildatensatz. Bauen Sie diese URL selbst auf, oder lesen Sie sie aus einem Response-Header Ihrer Anfrage aus.
Den ersten Aufruf löst der normale Start des zeitgesteuerten Profils aus. Danach startet das Profil automatisch erneut mit der URL aus der Variablen. Dabei entsteht jeweils ein weiterer Job. Die Checkbox ⑥ hat beim Paging keine Wirkung.
Der Vorgang wiederholt sich, bis die Variable denselben Wert wie beim letzten Request enthält. Er endet ebenfalls, wenn der letzte Request einen leeren Body liefert. Aktivieren Sie zusätzlich die Checkbox Weitere Seiten beim Paging über gleiche URL abrufbar, dann wiederholt sich der Vorgang auch bei unverändertem Variablenwert. ACHTUNG: Verwenden Sie diese Option mit Vorsicht. Sie kann sehr viele Jobs erzeugen. Nach 1000 Wiederholungen bricht der Eingangsagent automatisch ab.