REST Connector
Verwendung
Der REST Connector bietet eine Schnittstelle, um Daten via HTTP zu übertragen, ohne dass es dabei eine zusätzliche Transportschicht wie z.B. SOAP gibt. Der REST Connector wird genutzt, um REST-konforme Web Services über eine URL aufzurufen oder anzubieten.
Konnektortypen
Die Funktionen des REST Connectors hängen von der konkreten Konfiguration ab:
-
Input Listener Connector
Stellt eine Ressource unter einer angegebenen URL zur Verfügung, die von einem Client per Request angefragt werden kann. Die angebotene Ressource stellt dabei das Ergebnis einer Workflow-Ausführung dar.
Alle Parameter und Header, die mit dem Request übergeben wurden, stehen während der Workflow-Ausführung als Modulvariablen zur Verfügung.
-
Medium/Output Connector
Sendet als Client HTTP-Requests an einen HTTP-Server und gibt - im Fall des Medium Connectors - die zurückgelieferte Antwort (falls vorhanden) an den Workflow weiter.
Modulvariablen
Bei der Ausführung eines REST Connectors werden abhängig vom Konnektor-Typ folgende Variablen gesetzt und stehen im weiteren Verlauf der Workflow-Ausführung zur Verfügung:
Input Listener Connector
Für die Daten der empfangenen Anfrage werden folgende Variablen gesetzt:
-
restConnector.requestMethod
Enthält den Namen der HTTP-Methode der Anfrage.
-
restConnector.requestHeaders
Enthält die Header-Daten der Anfrage-Nachricht.
-
restConnector.requestQueryParams
Enthält die Werte der Query-Parameter aus der Anfrage-URL. Diese werden in eine XML-Struktur überführt und jeder Parameter wird in ein XML-Element umgesetzt.
-
restConnector.requestResourcePath
Enthält den Pfad der angeforderten Ressource. Die Variable enthält z.B. bei der Anfrage-URL
https://<server>:<port>/ibis/rest/rc/orders/123
den Wert/orders/123
. -
restConnector.requestURITemplateParam.x
Enthält die Inhalte von dynamischen Pfadbestandteilen der Anfrage-URL.
x
steht dabei jeweils für den in geschweiften Klammern stehenden Namen des Pfadbestandteils innerhalb der am Connector konfigurierten Ressourcen-URL. So werden z.B. bei der Ressourcen-URLusers/{userName}/auftraege/{auftragsNr}
die VariablenrestConnector.requestURITemplateParam.userName
undrestConnector.requestURITemplateParam.auftragsNr
mit den konkreten Werten aus der Anfrage-URL gesetzt. -
restConnector.clientAddress
Enthält die IP-Adresse des aufrufenden Clients.
-
restConnector.requestAuthUser
Enthält den Namen des authentifizierten Benutzers, falls bei den Authentifizierungs-Optionen Portal-Benutzerdaten verwenden ausgewählt wurde.
Die Status- und Header-Daten der zu versendenden Antwort werden in folgende Variablen geschrieben:
-
restConnector.responseStatusCode
Enthält Antwortcode für das Ergebnis der gesendeten Antwort.
-
restConnector.responseStatusDescription
Enthält die Beschreibung des Antwortcodes.
-
restConnector.responseHeaders
Enthält die Header-Daten der gesendeten Antwort-Nachricht.
Der Inhalt der Variablen entspricht den im Konnektor konfigurierten Standardwerten. Die Variablen dienen dazu, im Workflow dynamisch überschrieben zu werden. Der Wert der Variable, der am Ende des Workflows zur Verfügung steht, wird für den Versand der Antwort verwendet.
Medium/Output Connector
Die Status- und Header-Daten der empfangenen Antwort werden in folgende Variablen geschrieben:
-
restConnector.responseStatusCode
Liefert den Antwortcode, der das Ergebnis der Abfrage angibt.
-
restConnector.responseStatusDescription
Liefert die Beschreibung des Antwortcodes, z.B.
Internal Server Error
. -
restConnector.responseHeaders
Liefert die Header-Daten der Antwort-Nachricht.
REST-Funktionsprinzip
HTTP - Ressourcen - URLs
REST (Representational State Transfer) ist ein Architektur-Konzept für Web Services, das beschreibt, wie Web-Standards in einer Web-gerechten Weise einsetzt werden können. REST-basierte Web Services nutzen das HTTP-Protokoll und die HTTP-Methoden wie GET oder POST.
Ein Grundprinzip dieses Modells ist, dass die Funktionalität eines Web Service nicht in dessen Eigenschaften abgebildet wird, sondern in Ressourcen des Service. Die einzelnen Funktionen eines Dienstes werden dabei in einzeln über URLs adressierbare Ressourcen zerlegt.
REST bietet damit die Möglichkeit, Applikationen wie z.B. einen Online-Shop über eine URL zu adressieren. Dabei stellt jedes einzelne Objekt der Anwendung wie Artikel oder Kunde eine Ressource dar, die über eine eigene URL angesprochen wird.
Jede REST-Ressource besitzt über die verschiedenen HTTP-Methoden eine generische Schnittstelle.
Für das Beispiel eines Online-Shops als REST-Service gibt es bei der Auftragsverwaltung z.B. eine URL für die Menge der Bestellungen jedes Kunden und eine URL für jede Bestellung.
Die Kommunikation erfolgt nur bei Bedarf auf Abruf. Der Client bzw. Konnektor wird aktiv und fordert vom Server eine Repräsentation einer Ressource an bzw. modifiziert eine Ressource.
Ressourcen
Im Beispiel des Online-Shops stellt dieser eine Ansammlung von Ressourcen dar, an die per HTTP Nachrichten gesendet werden können, z.B. zum Aufruf eines Kunden zu einer Bestellung in einem Warenkorb. Die Ressource wird dabei nicht direkt manipuliert, denn der Zugriff erfolgt indirekt über die der Ressource zugeordnete URL.
Beispiele für Ressourcen
Online-Shop als Web Service:
https://<server>:<port>/ibis/rest/sqlshop
Auflistung aller Aufträge:
https://<server>:<port>/ibis/rest/sqlshop/orders
Auftrag mit der Nr. 1234:
https://<server>:<port>/ibis/rest/sqlshop/orders/1234
Repräsentationen
Jede Ressource kann verschiedene Repräsentationen haben, d.h. der Kunde kann z.B. durch eine XML-Struktur mit den Kundenstammdaten oder durch eine Visitenkarte im vcard-Format repräsentiert sein. Zwischen Client und Server muss ein gemeinsames Verständnis über die Bedeutung der Repräsentation durch die Verwendung von XML vorhanden sein.
Repräsentationen können auf weitere Ressourcen verweisen, die ihrerseits wieder Repräsentationen liefern, die wiederum auf Ressourcen verweisen können. Wenn ein Client einem Link in einer Repräsentation folgt, gelangt er zu einer anderen Ressource.
Beispiele für Repräsentationen
Repräsentation eines Kunden durch seine Stammdaten:
<CUSTOMER>
<ID>4</ID>
<FIRSTNAME>Heinz</FIRSTNAME>
<LASTNAME>Mustermann</LASTNAME>
<STREET>Musterstraße. 13</STREET>
<CITY>Musterstadt</CITY>
</CUSTOMER>
Repräsentation einer Kundenliste mit Verlinkungen auf die einzelnen Kunden als weitere Ressourcen:
<CUSTOMERList>
<CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/1/">1</CUSTOMER>
<CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/2/">2</CUSTOMER>
<CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/3/">3</CUSTOMER>
<CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/4/">4</CUSTOMER>
<CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/29/">29</CUSTOMER>
</CUSTOMERList>
Methoden
Das REST-Prinzip sieht vor, dass auf Ressourcen mit den Standard-HTTP-Methoden GET, POST, PUT und DELETE zugegriffen wird. Dadurch müssen keine Protokoll-Konventionen bekannt sein, damit Client und Server kommunizieren können. Eine Anfrage (Request), z.B. nach einer bestimmten Bestellung, besteht immer aus einer URL und einer HTTP-Methode. Die HTTP-Methoden bilden dabei die grundlegenden Aktionen auf den Ressourcen ab.
HTTP-Methoden im REST Connector verwenden
Die in den REST Connectoren konfigurierbaren HTTP-Methoden decken die Anwendungsfälle von REST-Anwendungen ab.
HTTP-Methode | Bedeutung |
---|---|
|
GET fragt die Repräsentation einer Ressource ab. GET-Requests können beliebig oft abgeschickt werden. |
|
Mit POST kann einer Ressource etwas hinzugefügt werden. Beispielsweise könnte eine Ware zu einem Warenkorb hinzugefügt werden. |
|
Neue Ressourcen können mit PUT erzeugt oder der Inhalt bestehender Ressourcen ersetzt werden. |
|
Mit PATCH können einzelne Attribute einer Ressource geändert werden. PATCH spart Bandbreite, da es partielle Aktualisierungen ermöglicht. Außerdem lässt sich mit PATCH (gegenüber PUT) präziser steuern, welche Attribute einer Resource geändert werden dürfen und welche nicht. |
|
Ressourcen können mit DELETE gelöscht werden. |
|
Liefert eine Liste mit den vom Server unterstützten Methoden. |
|
Genau wie bei GET wird eine Ressource angefragt, es wird jedoch in der Antwort kein Inhalt (Body) übertragen, sondern nur der Response Header. So kann z.B. vor einer GET-Anfrage die Dateigröße abgefragt werden. Um verschiedene Methoden auf eine Ressource anzuwenden, wird immer die gleiche URL verwendet, denn die URL ist unabhängig von der durchgeführten Aktion. |
Ressource anbieten
Prinzip
Einen Web Service in Form einer REST-Ressource können Sie durch einen Technical Workflow mit einem REST Input Listener Connector realisieren. Der REST Connector bietet dann nach außen eine Ressource (z.B. eine Auftrags- oder Artikelliste) in Form einer URL an. Einzelne Ressourcen werden jeweils über einen einzelnen REST Input Connector angeboten.
Die Ressourcen sind einzelne Objekte einer Anwendung, die über eine URL erreichbar sein müssen und mit einem Dokument, vorzugsweise in XML, repräsentiert werden können.
So gehen Sie vor
-
Ressource konfigurieren
-
Erstellen Sie einen REST Input Listener Connector.
-
Wählen Sie aus der Liste unter Vorgaben verwenden für, welche Art von Ressource dieser Konnektor anbieten soll.
-
Definieren Sie eine URL, unter der auf die Ressource zugegriffen werden kann.
Für dynamische Pfadbestandteile können geschweifte Klammern verwendet werden, z.B.
https://<server>:<port>/ibis/rest/orders/{orderID}
. Hier wird der Wert vonorderID
als Workflow-Variable im Workflow zur Verfügung gestellt und kann benutzt werden, um die Daten des gewünschten Auftrags zu ermitteln, siehe Modulvariablen. Geben Sie*
am Ende des Pfades ein, um Pfade zu unterstützen, die mit beliebigen Zeichen enden. -
Sichern Sie Ihren Rest-Service vor unzulässigen Zugriffen durch Aktivieren der Option Authentifizierung erforderlich.
-
Legen Sie die gewünschte Authentifizierungsmethode fest und geben Sie die für einen Request erforderlichen Zugangsdaten an.
-
Legen Sie fest, welche Operationen auf Ihrer Ressource ausgeführt werden können.
Es sind nicht für jeden Ressourcentyp alle HTTP-Methoden zugelassen. Standardmäßig sind die für eine gewählte Ressource sinnvollen HTTP-Methoden vorausgewählt.
-
Legen Sie die Kodierung für Daten fest, die als Request im Format
multipart/form-data
eingehen.
-
-
Antwort konfigurieren
Sie definieren für jede zulässige HTTP-Methode, mit der die Ressource angefragt werden kann, die von der Ressource zurückgelieferte Antwort.
-
Konfigurieren Sie für die verfügbaren Anfrage-Typen die Antwortdaten.
Die hier konfigurierten Werte können im Workflow dynamisch über das Ändern entsprechender Variablen geändert werden.
Siehe Modulvariablen
-
Bei Ressourcen mit mehreren unterstützten Methoden ist die Variable |
Beispiel für Sammel-Ressource
Beispiel für Einzel-Ressource aus Sammlung
Bei eingehenden Requests mit HTML-Form-Daten und dem Content-Type |
Verfügbare Input REST Connectoren anzeigen
Sie können sich eine Liste aller in INUBIT Workbench erstellten, verfügbaren, aktiven und inaktiven REST Input-Konnektoren anzeigen lassen.
So gehen Sie vor
-
Wählen Sie einen REST Input Listener Connector aus und öffnen Sie diesen zum Bearbeiten.
-
Klicken Sie im Dialog im Bereich Bereitgestellte Ressourcen neben der URL auf .
-
Wählen Sie die Option Alle REST Input-Konnektoren auflisten.
Ein Dialog öffnet sich, das eine Liste aller angelegten Input Connectoren anzeigt. In der Liste wird der Name des Konnektors, der entsprechende Workflow, der Pfad für die Ressource und die für den Konnektor verfügbaren HTTP-Methoden aufgeführt.
Darüber hinaus können Sie sich eine Liste aller angebotenen REST-Services im Web-Browser anzeigen lassen:
https://<server>:<port>/ibis/rest/rc?method=OPTIONS
Publizierte REST-Ressourcen anzeigen
Sie können sich eine Liste mit allen publizierten und aktivierten Ressourcen anzeigen lassen.
So gehen Sie vor
-
Wählen Sie einen REST Input Listener Connector aus und öffnen Sie diesen zum Bearbeiten.
-
Klicken Sie im Dialog im Bereich Bereitgestellte Ressourcen neben der URL auf .
-
Wählen Sie die Option Publizierte Ressourcen anzeigen. Im Browser öffnet sich eine Seite, die aufbereitete Liste mit allen aktivierten Ressourcen anzeigt.
Ressourcen, die mit einem REST Input Listener Connector realisiert sind, werden erst als publiziert und aktiviert angezeigt, wenn die entsprechenden Technical Workflows aktiviert sind. |
REST-Ressource aufrufen
Prinzip
Sie können mit dem REST Connector eine Ressource, die über eine bestimmte URL zur Verfügung steht, aufrufen. So können Sie z.B. eine Artikelliste anfordern. Sie müssen dazu einen REST Output oder Medium Connector zum Versenden der Anfrage und zum Empfangen der Antwort anlegen und konfigurieren.
-
Medium Connector
Verwenden Sie den Medium Connector, wenn die aufgerufene Ressource eine Antwort zurücksendet, die im Workflow weiterverarbeitet werden soll.
-
Output Connector
Verwenden Sie den Output Connector, wenn die Anfrage an eine Ressource ein Aufruf ohne Rückgabe ist.
Voraussetzungen
-
URL der aufzurufenden Ressource ist verfügbar.
-
Authentifizierungsdaten sind verfügbar, falls der Server für die Ressource eine Authentifizierung fordert.
So gehen Sie vor
-
Legen Sie einen neuen REST Medium oder Output Connector.
-
Geben Sie die URL der aufzurufenden Ressource ein.
-
Geben Sie ggf. die erforderlichen Authentifizierungsdaten ein.
-
Wählen Sie je nach Art der Anfrage die gewünschte HTTP-Methode.
-
Falls Sie als Methode PUT oder POST gesetzt haben, wählen Sie jeweils eine Option aus der Liste der Medientypen und des Zeichensatzes aus.
Damit legen Sie die Definition der Daten fest, die verschickt werden. Die Werte der Anfragedaten werden in den Content-Type-Header übernommen.
-
Optional können Sie Anpassungen im Request-Header vornehmen, z.B. wenn Sie für Ressourcen, die mehrere Repräsentationen unterstützen, die gewünschte Repräsentation der angefragten Ressource festlegen wollen. Dazu nutzen Sie den
Accept
-Header:-
Klicken Sie auf den Button Header bearbeiten. Ein Dialog öffnet sich. Standardmäßig wird mit / eine beliebige Repräsentation einer Ressource abgefragt.
-
Doppelklicken Sie den
Accept
-Header. Ein weiterer Dialog öffnet sich: -
Wählen Sie einen Medien-Typen aus. Sie können auch mehrere Typen auswählen und es wird dann eine geordnete Liste der gewünschten Repräsentationen zurückgeliefert.
-
Schließen Sie die Dialoge zum Bearbeiten des HTTP-Headers mit OK.
-
-
Klicken Sie Fertig stellen.
-
Publizieren Sie den REST Connector.
Für das Abfragen einer Ressource mit GET benötigen Sie keine Ausgangsnachricht, da die Ressource nur angefragt, jedoch keine Änderung an den Daten vorgenommen werden. Für das Zugreifen auf eine Ressource mit POST oder PUT benötigen Sie eine Ausgangsnachricht. Falls Sie z.B. Daten in eine Artikelliste hinzufügen möchten, können Sie mit einem XSLT Converter im Workflow vor dem REST Connector eine XML-Nachricht erstellen und diese mit versenden, z.B.:
<artikel>
<beschreibung>Rooibusch-Tee</beschreibung>
<preis>2,80</preis>
<einheit>100g</einheit>
</artikel>
Alle Eingangsnachrichten in den REST Output/Medium Connector werden mit der Anfrage versendet.
Sie können die aufzurufende URL der Ressource dynamisch anpassen, indem Sie die Moduleigenschaft |
Header dynamisch setzen und überschreiben
Verwendung
Sie können das Variablenmapping nutzen, um Header zu überschreiben oder um neue Header zu setzen, siehe Workflow-Variablen und Mappings.
So gehen Sie vor
-
Um Response-Header in einem Workflow mit einem REST Input Listener Connector zu überschreiben, setzen Sie die Workflowvariablen
restConnector.ResponseHeader.[headerName]
irgendwo im Workflow bevor die Antwort als Ausgangsnachricht zurückgegeben wird.Die folgenden Response-Header werden vom REST Connector selbst gesetzt und können nicht vom Benutzer überschrieben werden, z.B. über das Variablenmapping.
Allow Connection Content-Length Content-Encoding Content-Type Content-MD5 Content-Range Proxy-Authenticate Server Via WWW-Authenticate
-
Um Request-Header für die Anfrage eines REST Medium oder Output Connector-Moduls zu überschreiben, setzen Sie die Moduleigenschaften
Request.Header.[headerName]
des REST Connector-Moduls.Die folgenden Request-Header werden vom REST Connector selbst gesetzt und können nicht vom Benutzer überschrieben werden, z.B. über das Variablenmapping.
Accept Accept-Charset Accept-Encoding Accept-Language Cookie Expect From Host If-Match If-Modified-Since If-None-Match If-Range If-Unmodified-Since Max-Forwards Proxy-Authorization Range Referer User-Agent
Dialogbeschreibungen
Dialog Konfiguration der Ressource
(Input Listener Connector)
In diesem Dialog legen Sie den Pfad für die vom Konnektor angebotene Ressource, die Authentifizierung und die HTTP-Methoden fest.
Bereitgestellte Ressource
-
Vorgaben verwenden für
Wählen Sie aus, welchen Typ von Ressource der Konnektor anbieten soll. Die Wahl des Ressourcen-Typs legt gleichzeitig die Vorauswahl der standardmäßig unterstützten HTTP-Methode(n) fest.
Siehe Unterstützte HTTP-Methoden unten
-
Einzelne Ressource
Wählen Sie die Option, wenn nur lesend auf eine einzelne Ressource zugegriffen werden soll, z.B. Bestellung anzeigen. Es wird automatisch die HTTP-Methode
GET
vorausgewählt. -
Sammel-Ressource
Wählen Sie die Option, wenn die Ressource z.B. eine Liste von Aufträgen (
/auftraege
) umfassen soll und diese Liste abgerufen oder der Liste neue Einträge hinzugefügt werden sollen. Es sind standardmäßig nur die Methoden GET und POST erlaubt. -
Einzel-Ressource aus Sammlung
Wählen Sie diese Option, wenn Sie z.B. einen einzelnen Auftrag aus einer Auftragsliste oder eine Artikelnummer als Ressource anbieten wollen. Unterstützte Methoden sind hier GET (Daten abrufen), PUT (Daten ändern) und DELETE (Daten löschen).
-
-
URL
URL des Input Listeners, unter welcher dieser auf Requests wartet und seine Ressource zur Verfügung stellt. Die URL ist standardmäßig nach folgendem Muster vorbelegt:
http(s)://[ServerName]:[Port]/ibis/rest/rc/[NamedesInputListeners]
Passen Sie ggf. den Teil der URL hinter
rc
beliebig an. Für dynamische Pfad-Bestandteile können geschweifte Klammern verwendet werden, z.B. /users/{userName}/auftraege/{auftragsNr}.Geben Sie
*
am Ende des Pfades ein, um Pfade zu unterstützen, die mit beliebigen Zeichen enden.
Authentifizierung erforderlich
Markieren Sie diese Option, wenn für den Zugriff auf die Ressource eine Authentifizierung erforderlich sein soll.
-
Statische Zugangsdaten verwenden
Definieren Sie hier ein zu verwendendes Verfahren und die für den Zugriff erforderlichen Authentifizierungsdaten.
-
Verfahren
-
Basic: Es werden Benutzername und Passwort verlangt und unverschlüsselt übermittelt.
Nur zu verwenden, wenn die Verbindung zwischen Client und Server als sicher betrachtet werden kann!
-
Digest: Verlangt ebenfalls Benutzername und Passwort. Das Passwort wird verschlüsselt übertragen. Für die Verschlüsselung werden mehrere Parameter verwendet, u.a. zufällig erzeugte Werte.
-
-
Benutzername: Benutzername für die Authentifizierung.
-
Passwort: Passwort für die Authentifizierung
-
-
Aus dem Credentials Manager auswählen
Für die Authentifizierung können Sie auch Zugangsdaten verwenden, die im Credentials Manager verwaltet werden. Siehe Credentials Manager für die Authentifizierung verwenden.
-
Prozessbenutzer verwenden
Diese Option ist nur bei einem installierten Portal verfügbar.
Wenn die Option aktiviert ist, ist der Zugriff auf die Ressource nur möglich, wenn gültige Portal-Benutzerdaten übergeben werden.
Als Authentifizierungsverfahren wird Basic verwendet.
Der in einem Aufruf verwendete Portal-Benutzername steht bei Workflow-Ausführung in der Variable
restConnector.requestAuthUser
zur Verfügung.Siehe Modulvariablen>
-
Process Engine Benutzer verwenden (Passwort aus Portalkonfiguration)
Verwendung des internen Benutzers (
INUBITISPortalUser@@@intern
) und des Passworts für die Process Engine; zu finden in der INUBIT Workbench unter dem Register Konfiguration > Verwaltung > Server > Passwort für die Process Engine.Weitere Informationen zur Verwendung des internen Benutzers über das FormProxyServlet siehe Zugriff auf einen REST-Input-Listener-Connector und siehe Zugriff auf einen gesicherten HTTP-Input-Listener-Connector.
-
Keycloak-Autorisierung für den REST Connector verwenden
-
REST Listener
Wenn ausgewählt, wird die Authentifizierung gegen den Keycloak-Ressourcenserver im REST Connector-Listener aktiviert. Dadurch kann sich der registrierte Client mit den ihm zugeordneten Benutzern gegen den Keycloak OIDC-Server authentifizieren.
Um die notwendigen Informationen für die Keycloak-Authentifizierung hinzuzufügen, klicken Sie auf Konfigurationsdatei auswählen…, um den Dialog Auswahl der JSON Konfigurationsdatei zu öffnen. Vorausgesetzt, Sie haben diese Informationen in einer
keycloak.json
-Datei bereitgestellt, die im INUBIT-Repository gespeichert ist, können Sie diese JSON-Datei aus dem INUBIT-Repository laden, indem Sie auf die entsprechende Schaltfläche neben dem Eingabefeld Auswahl aus dem Repository klicken.Alternativ können Sie den Inhalt der Datei
keycloak.json
direkt kopieren und in den Textbereich Inhalt der JSON-Datei einfügen.Sobald der REST Connector-Listener ausgeführt wird, verwendet er die URL des Authentifizierungsservers und authentifiziert sich gegenüber dem Ressourcenserver. Das Textfeld ist für die Well known URL (https://<hostname>:<port>/auth/realms/<keycloak realm name>/.well-known/openid-configuration) vorgesehen, die für die Generierung des Tokens und die Authentifizierung anhand des Tokens verwendet wird. Sie ist für die Authentifizierung mit Anmeldeinformationen und Token erforderlich.
-
REST-Aufrufer
Mit dem REST Connector kann man den REST Listener oder REST-Ressourcen aufrufen, die mit Keycloak autorisiert sind. Um diese Aktivität durchzuführen, gibt es zwei Optionen.
-
Benutzername und Passwort verwenden: Um auf den REST Connector-Listener zuzugreifen, verwenden Sie die "Listener-URL", das Authentifizierungsverfahren "Basic" und den Benutzernamen und das Passwort von Keycloak auf der Seite Konfiguration der Anfrage. Auf dem Keycloak-Server würden beispielsweise der Benutzer "Keycloak_admin“ und die Benutzeranmeldeinformationen “test” erstellt. Hier müssen dieselben Anmeldeinformationen bereitgestellt werden (siehe untenstehendes Bild).
-
Autorisierungs-Token verwenden: Um auf den REST Connector-Listener über "Bearer Token" zuzugreifen, bearbeiten Sie die HTTP-Header auf der Seite Konfiguration der Anfrage. In den HTTP-Header geben Sie den Namen "x-openid-token" und den Wert des Zugriffs-Tokens an. (siehe untenstehendes Bild).
Verwenden Sie diesen CURL-Befehl, um ein Token in Keycloak zu erzeugen:
curl --request POST --url https://<keyclok-server>/auth/realms/<realm name>/protocol/openid-connect/token --header 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=password&client_id=<client-id>&client_secret=<client_secret>&username=<userName>&password=<password>'
Kopieren Sie den Access Token aus der Ausgabe in den Wert des Header-Parameters "x-openid-token".
Benutzername und Passwort sind für den Zugriff auf den REST Connector-Listener mit Autorisierungs-Token nicht erforderlich.
-
-
Unterstützte HTTP-Methoden
Hier legen Sie fest, dass der Konnektor nur auf bestimmte HTTP-Operationen reagiert.
Durch die Definition des Ressourcen-Typs haben Sie bereits automatisch zum jeweiligen Ressourcen-Typ passende HTTP-Methoden voreingestellt.
-
GET (Daten der Ressource abrufen)
-
POST (neue Ressource anlegen)
-
PUT (Ressource aktualisieren)
-
PATCH (Ressource ändern)
-
DELETE (Ressource löschen)
Aufbereitung empfangener Daten
-
Legen Sie die Kodierung für Daten fest, die als Request im Format
multipart/form-data
eingehen. -
CORS verwenden
Wählen Sie diese Option, wenn Sie die CORS-Eigenschaften verwenden möchten. Um die Eigenschaften zu konfigurieren, klicken Sie auf Einstellungen… In dem sich öffnenden Dialog CORS Einstellungen können Sie die folgenden Einstellungen konfigurieren:
-
Allowed origins (Zulässige Quell-Domänen)
Geben Sie entweder eine einzelne Quelle-Domäne oder mehrere Quell-Domänen an. Damit wird den Browsern mitgeteilt, dass diese Quell-Domäne auf die Ressourcen zugreifen dürfen. Mehrere Quell-Domänen müssen durch Kommas ohne Leerzeichen getrennt werden. Um alle Quell-Domänen zuzulassen, geben Sie "*" an.
-
Allowed methods (Zulässige Methoden)
Wählen Sie die beim Zugriff auf die Ressource zulässigen Methoden aus oder heben Sie die Auswahl auf.
-
Allowed headers (Zulässige Header)
Geben Sie an, welche HTTP-Header bei der aktuellen Anfrage verwendet werden können.
-
Allow credentials (Erlaube Anmeldeinformationen)
Wählen Sie diese Option, um festzulegen, dass die aktuelle Anfrage mit Anmeldeinformationen durchgeführt werden kann.
-
MaxAge (Maximales Alter)
Geben Sie an, wie lange die Ergebnisse einer Preflight-Anfrage zwischengespeichert werden können.
-
Dialog Konfiguration der Antwort im REST Connector
(Input Listener Connector)
In diesem Dialog legen Sie die Einstellungen für die zuvor ausgewählten und von Ihrem Konnektor unterstützten HTTP-Methoden fest, die für eine Antwort genutzt werden.
Einstellungen für GET-Anfragen
Legen Sie hier fest, wie die Repräsentation der Antwort-Daten bei GET-Requests aussehen soll. Die Standard-Einstellungen sind bereits sinnvoll gewählt und können belassen werden.
-
Medien-Typ
Wählen Sie den gewünschten Medien-Typ aus.
Informationen zu MIME-Typen siehe https://de.wikipedia.org/wiki/Internet_Media_Type und siehe https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types.
-
Zeichensatz
Wählen Sie den Zeichensatz der Antwort-Daten aus.
Einstellungen für POST und PUT-Anfragen
-
Workflow asynchron starten
Aktivieren Sie diese Option, wenn der Input Listener nach dem Empfang des Request die HTTP-Statusmeldung direkt an den Client zurückliefern soll. In diesem Fall wird die Antwort vor dem Start des Workflows geschickt. Das Ergebnis des Workflows wird nicht zurückgegeben. Falls die Option nicht aktiviert ist, startet der Workflow synchron und die Antwort wird erst an den Client zurückgeschickt, nachdem das letzte Modul des Workflows ausgeführt wurde.
-
Antwort-Statuscode
Wählen Sie aus, was als Antwort-Statuscode empfangen werden soll.
Um im Fehlerfall in der Response anzuzeigen, dass die Anfrage-Daten fehlerhaft sind, kann die Variable
restConnector.responseStatusCode
für den Antwort-Statuscode auf den HTTP-Status-Code 400 (für Bad Request) gesetzt werden.
Allgemeine Einstellungen
-
Antwort-Daten automatisch kodieren
Aktivieren Sie diese Option, wenn die Antwort-Daten automatisch mit einer dem Server bekannten und vom Client unterstützten Methode kodiert werden sollen.
-
HTTP-Header bearbeiten
Der Button HTTP-Header bearbeiten öffnet den Dialog zum Bearbeiten der Header-Definition für die verfügbaren HTTP-Methoden.
Dialog Konfiguration der Anfrage
(Medium und Output Connector)
Im Dialog zur Konfiguration der anzufragenden Ressource legen Sie die aufzurufende URL, die HTTP-Methode und evtl. eine Authentifizierung fest.
Basiskonfiguration
-
Aufzurufende URL
Geben Sie die URL der Ressource ein, an den der Connector seinen Request sendet, zum Beispiel Adresse eines HTTP Input Listeners.
-
SSL
Dient zum Konfigurieren der Server- bzw. Client-Authentifizierung.
Siehe Dialog SSL-Konfiguration
-
-
Methode
Geben Sie hier die gewünschte HTTP-Methode an, mit der die Aktion, die auf die Ressource angewendet werden soll, definiert wird.
-
Redirects automatisch weiterverfolgen (nur für die GET-Methode)
-
Wenn die Checkbox aktiviert ist, ruft der REST Connector die von der angefragten Applikation für die Weiterleitung bereitgestellte URL auf, wenn der HTTP-Statuscode 302 als Antwort auf einen GET-Request empfangen wurde.
Die für die Weiterleitung konfigurierte URL wird aufgerufen, solange der HTTP-Statuscode 302 empfangen wird.
-
Wenn die Checkbox aktiviert ist (Standard), schlägt der GET-Request fehl, wenn der HTTP-Statuscode 302 empfangen wird.
-
Authentifizierung verwenden
Markieren Sie diese Option, wenn der Server eine Authentifizierung fordert.
-
Folgende Zugangsdaten verwenden
-
Verfahren
-
Basic: Es werden Benutzername und Passwort verlangt und unverschlüsselt übermittelt.
Nur zu verwenden, wenn die Verbindung zwischen Client und Server als sicher betrachtet werden kann!
-
Digest: Verlangt ebenfalls Benutzername und Passwort. Das Passwort wird verschlüsselt übertragen. Für die Verschlüsselung werden mehrere Parameter verwendet, u.a. zufällig erzeugte Werte.
-
-
Statische Zugangsdaten verwenden
Geben Sie dann den Account ein, den der Connector für die Authentifizierung verwenden soll.
-
Benutzername: Benutzername für die Authentifizierung.
-
Passwort: Passwort für die Authentifizierung.
-
-
Aus dem Credentials Manager auswählen
Für die Authentifizierung können Sie auch Zugangsdaten verwenden, die im Credentials Manager verwaltet werden. Siehe Credentials Manager für die Authentifizierung verwenden.
-
-
Authentifizierung für Zugriff auf Process Engine verwenden
Verwendung des internen Benutzers (
INUBITISPortalUser@@@intern
) und des Passworts für die Process Engine, zu finden in der INUBIT Workbench unter dem Register Konfiguration > Verwaltung > Server > Passwort für die Process Engine.
Autorisierung
-
OAuth2-Autorisierung verwenden
Aktivieren Sie diese Option, um die OAuth2-Autorisierung zu verwenden
Wenn die Option OAuth2-Autorisierung verwenden ausgewählt ist, hat die OAuth2-Autorisierung Vorrang vor den Einstellungen im Bereich Authentifizierung verwenden.
-
Grant-Typ (Gewährungstyp)
-
Client Credentials: Empfohlene Option für INUBIT, da keine Benutzerinteraktion erforderlich ist.
-
Password Credentials
-
Benutzerdefiniert: Wählen Sie diese Option, um andere Grant-Typen zu konfigurieren (z.B. Refresh Token Flow, Implicit Flow)
-
-
URL des Zugriffs-Tokens
Fügen Sie die URL des OAuth Servers ein. Zusätzlich können Sie festlegen, ob der HTTP-Zugriff via GET oder POST erfolgen soll.
-
Parameter
Jeden Grant-Typ erfordert die Angabe bestimmter Parameter. Welche das sind, entnehmen Sie der Dokumentation des verwendeten OAuth Servers.
Die Parametertabelle kann beliebig viele Einträge aufnehmen.
Alle im Modulassistenten konfigurierten Parameter sind als Moduleigenschaften mit dem Präfix
OAUTH_PROPERTY
für die Verwendung im Variablen-Mapping verfügbar.Via Variablen-Mapping können nur Eigenschaften überschrieben werden, die vorher im Assistent gesetzt wurden. Sollen weitere Parameter via Variablen-Mapping gesetzt werden, müssen diese zuvor über den Modulassistenten in der Tabelle eingetragen werden (mit leerem oder Platzhalterwert).
Anfragedaten
Hier legen Sie die gewünschte Repräsentation der Anfragedaten fest.
-
Eingehenden Datenstrom als HTTP-Payload senden
Aktivieren Sie diese Checkbox, um die Eingangsnachricht als HTTP-Payload zu senden.
Diese Funktionalität kann optional verwendet werden, um anzugeben, ob die Eingangsnachricht als REST-Aufrufer- Nutzdaten für HTTP-Methoden wie
GET
undDELETE
weitergeleitet werden soll. -
MIME-Typ
Wählen Sie aus der Liste MIME-Typ einen Inhaltstyp aus oder tragen Sie den Inhaltstyp manuell ein und wählen Sie aus der Liste Kodierung einen Zeichensatz aus.
Für die HTTP-Methoden
POST
,PUT
undPATCH
wird der eingehende Datenstrom standardmäßig als HTTP-Payload gesendet.Für die HTTP-Methoden
GET
,DELETE
,OPTIONS
undHEAD
müssen Sie dafür die Option Eingehenden Datenstrom als HTTP-Payload senden markieren.Wenn Sie einen benutzerdefinierten Begrenzungswert angeben (z.B.
myownboundaryvalue
), wird dieser beim Aufruf der REST-Anfrage berücksichtigt und nicht der automatisch generierte Wert. Verwenden Sie hierfür den MIME-Typmultipart/form-data; boundary=myownboundaryvalue
. -
Kodierung
Wählen Sie den Zeichensatz, den die Datei verwendet.
-
Als einzelne multipart/form-data Nachricht versenden
Aktivieren Sie diese Checkbox, um eine Eingangsnachricht als MIME-Daten zu senden und hochzuladen.
Ist diese Checkbox deaktiviert, muss die Eingangsnachricht als gültige MIME-Daten vorliegen.
-
Parametername für den Dateiinhalt (nur für den MIME-Typ
multipart/form-data
)Geben Sie den Parameternamen für den Dateiinhalt an.
Dieser Parameter wird verwendet, um den Wert des Parameters
name
imContent-Disposition
-Header zu setzen.Der
Content-Disposition
-Header ist Teil desmultipart/form-data
-Body. DerContent-Disposition
- Header wird verwendet, um Informationen für jeden Subpart der Form bereitzustellen. In erster Linie wirdform-data
verwendet, und der Header muss auch den Parametername
enthalten, damit das entsprechende Feld auf dem REST-Provider identifiziert/zugeordnet werden kann. Dieses Pflichtfeld muss durch den Benutzer angegeben werden.Beispielvorlage
-----------------------------9051914041544843365972754266 Content-Disposition: form-data; name="file1"; filename="a.txt" Content-Type: text/plain Content of a.txt. -----------------------------9051914041544843365972754266
Fälle
Es gibt zwei Fälle, den Wert für das Feld Parametername für den Dateiinhalt konfigurieren in Abhängigkeit davon, ob ein REST Connector-Listener oder ein externer REST-Endpunkt von einem INUBIT REST-Aufruf verwendet wird. Die folgende Beschreibung erläutert, wie das Feld Parametername für den Dateiinhalt in einem REST-Aufrufer konfiguriert werden muss.
-
Wenn Sie einen Aufruf an einen INUBIT REST-Listener senden, können Sie im REST-Aufrufer für den Parameter
name
im Feld Parametername für den Dateiinhalt einen eigenen Wert setzen. -
Wenn der REST-Aufrufer eine Anfrage an einen externen REST-Endpunkt sendet, unterscheidet sich das Verfahren, weil diese Endpunkte durch das Eingeben des Parameters
name
so eingebunden werden müssen, dass dieser demContent-Disposition
-Body zugeordnet werden kann. Daher müssen Sie als Parametername für den Dateiinhalt denselben Wert eingeben, der vom Anbieter des externen REST-Endpunkts bereitgestellt wurde. Da dies ein allgemeiner Standard desContent-Disposition
-Header ist, ist dieser Wert ein Pflichtparameter.
-
-
Eingangsnachricht verwenden (nur für den MIME-Typ
multipart/form-data
, wenn das Feld Parametername für den Dateiinhalt korrekt gesetzt ist)Wählen Sie diese Option, um eine Datei aus der Eingangsnachricht am REST Connector als zu sendende Datei anzugeben. Geben Sie auch die korrekte Dateierweiterung an.
-
Datei-URL verwenden (nur für den MIME-Typ
multipart/form-data
, wenn das Feld Parametername für den Dateiinhalt korrekt gesetzt ist)Wählen Sie diese Option, um die URL einer Datei im Server-Dateisystem einzugeben, damit diese hochgeladen werden kann.
HTTP-Header
Die Angaben im Request-Header informieren den Server, zum Beispiel über die Art und Konfiguration des Clients und die vom Client erwarteten bzw. unterstützten Dokumentformate. Hier legen Sie, zum Beispiel fest, in welcher Repräsentation man eine Liste mit angefragten Aufträgen erhalten will.
Der Button Header bearbeiten… öffnet einen Dialog. In dem Dialog können Sie den Request-Header durch Doppelklick auf die einzelnen Zeilen der Header-Liste definieren.
Die zulässigen Header sind in der HTTP-Spezifikation festgelegt, siehe https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.3.
Erweitert
-
Bei Fehlerantwort Fehler werfen
Per Default ist die Option Bei Fehlerantwort Fehler werfen aktiviert. Somit wird bei einer vom REST Connector empfangenen Fehlerantwort (HTTP-Statuscode
4xx
oder5xx
) ein Workflow-Fehler ausgelöst.Deaktivieren Sie die Option, um den Workflow nach einer Fehlerantwort normal fortzusetzen. Die Antwort-Daten erscheinen dann in dem MIME-Typ bzw. in den für den REST-Connector spezifischen Variablen.
-
Tatsächliche Fehlermeldung als Variable ISErrorString zurückgeben
Aktivieren Sie diese Option, damit die tatsächliche Fehlermeldung als Variable
ISErrorString
anstelle der INUBIT- eigenen Fehlermeldung zurückgegeben wird.
Test
-
Button Versand der Anfrage testen
Zum Prüfen, ob die Verbindung mit Ihren Angaben erfolgreich aufgebaut werden kann. Der Button öffnet einen Dialog, in dem die konfigurierte Verbindung getestet werden kann und eine Antwort mit Status-Code, HTTP-Header und Daten angezeigt wird.