Mit REST-Aufgaben arbeiten

Um einen REST-API-Endpunkt aufzurufen, geben Sie die Informationen zum Ausführen und Abschließen der REST-Anforderung in einer REST-Aufgabe an.

Das Erstellen einer REST-Task umfasst die folgenden Hauptschritte:

• Ausführungsdetails definieren: Definieren Sie die Ausführungsdetails für die REST-Anforderung, einschließlich HTTP-Methode, URL und Anforderungsheader.

  Die URL ist der zu kontaktierende REST-Server und der relative Pfad zur Ressource, auf die Sie in der Anforderung zugreifen möchten. Beispiel:

  http://myserver.com:8081/workspaces/finance1234/dataAssets

  Bei einer POST- oder PUT-Methode geben Sie auch den Anforderungsbody an. Derzeit wird nur JSON als Format für einen Anforderungsbody unterstützt.

  Die Definition von Ausführungsdetails in Data Integration ist für API-Vorgänge mit kurzer Ausführung und API-Vorgänge mit langer Ausführungszeit identisch.

• Abschlusskriterien angeben: Geben Sie die Kriterien für die Erfolgsbedingung an, die erfüllt sein müssen, damit die REST-Aufgabe als erfolgreich abgeschlossen gilt.

  Schreiben Sie die Bedingung, die anhand der Antwort des REST-Aufrufs im Ausführungsschritt als "true" oder "false" ausgewertet wird. Wenn die Bedingung "true" zurückgibt, ist das Ergebnis der REST-Aufgabe erfolgreich. Bei "false" ist das Ergebnis eine nicht erfolgreiche REST-Aufgabe.

  Data Integration stellt eine Standarderfolgbedingung bereit, die Sie verwenden oder bearbeiten können.

  Wenn Sie Abschlusskriterien für einen API-Vorgang mit langer Laufzeit angeben, müssen Sie eine Polling-Bedingung und andere Polling-Werte hinzufügen. Das Hinzufügen einer termination-Anforderung ist optional.

Informationen hierzu finden Sie auch unter Parameter in einer REST-Aufgabe sowie Informationen, die Sie einrichten müssen, bevor Sie mit dem Oracle Cloud Infrastructure-Resource Principal einen API-Endpunkt in einer REST-Aufgabe authentifizieren.

Bei einem REST-API-Vorgang mit langer Ausführungszeit müssen Sie zusätzlich zu einer Erfolgsbedingung eine Polling-URL und -Bedingung sowie Polling-Intervall- und -Timeoutwerte angeben, um den Abschluss des REST-Aufrufs zu identifizieren.

Mit der Polling-Konfiguration wird der Status des REST-Aufrufs, der beim Ausführungsschritt aufgerufen wird, regelmäßig abgerufen.

Beim Polling ist die Erfolgsbedingung ein Ausdruck, der anhand der Antwort der Polling-Anforderung geschrieben wird. Der Polling-Aufruf wertet die Polling-Bedingung aus, um zu bestimmen, ob das Polling gestoppt oder fortgesetzt wird. Data Integration gibt im angegebenen Abfrageintervall wiederholt einen Polling-Aufruf aus, bis der Wert für den angegebenen Polling-Timeout erreicht wird oder bis die Polling-Bedingung "false" zurückgibt, je nachdem, was zuerst auftritt.

Das Polling-Intervall entspricht der Wartezeit vor dem Senden der nächsten Polling-Anforderung. Der Polling-Timeout ist die maximale Zeitspanne, während der wiederholtes Polling in der angegebenen Intervallrate ausgeführt werden darf. Der Intervallwert muss kleiner als der Timeoutwert sein.

Angenommen, der Polling-Timeout beträgt 24 Stunden und das Polling-Intervall 1 Stunde. Nachdem die REST-Anforderung beim Ausführungsschritt aufgerufen wurde, wird die Polling-REST-Anforderung in 1-Stunden-Intervallen gesendet, jedoch nur für bis zu 24 Stunden oder bis die Polling-Bedingung "false" zurückgibt.

Wenn die in der Erfolgsbedingung angegebenen Kriterien erfüllt sind, wurde der REST-Aufruf erfolgreich abgeschlossen. Dann wird die REST-Aufgabenausführung als erfolgreich betrachtet. Wenn die Erfolgsbedingung "false" zurückgibt, wird das Ergebnis der REST-Aufgabenausführung als nicht erfolgreich betrachtet.

Beispiel: Die Polling-Konfiguration fragt den Fortschritt einer Aufgabenausführung ab, indem der Status in der Antwort ausgewertet wird:

cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) != 'SUCCESS' or cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) != 'ERROR'

Polling wird gestoppt, wenn die Erfolgsbedingung erfüllt ist.

cast(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.status') as String) == 'SUCCESS'

Die Konfiguration der HTTP-Methode und der REST-URL zum Beenden des REST-Aufrufs ist für API-Vorgänge mit langer Ausführungszeit optional.

Die Definition der Details für die REST-Abbruchanforderung in Data Integration ähnelt der Definition der REST-Anforderung im Ausführungsschritt. Sie können jedoch Ausdrücke, die die API-Antwort aus dem REST-Ausführungsschritt verwenden, in die Beendigungs-URL aufnehmen.

Wenn Sie eine REST-Aufgabenausführung beenden und in dieser REST-Aufgabe keine Beendigungskonfiguration angegeben ist, führt Data Integration folgende Schritte aus:

• Die REST-Aufgabenausführung wird gestoppt.
• Der zugrunde liegende API-Vorgang, der von der REST-Aufgabe aufgerufen wurde, wird nicht gestoppt.

Wenn eine Beendigungskonfiguration angegeben ist, stoppt Data Integration die REST-Aufgabenausführung und den zugrunde liegenden API-Vorgang.

Geben Sie die Authentifizierung zum Aufrufen des REST-API-Endpunkts in der REST-Aufgabe an.

Derzeit können Sie den Oracle Cloud Infrastructure-Ressourcen-Principal als Methode zur Authentifizierung von Oracle Cloud Infrastructure-API-Endpunkten verwenden. Sie können den Workspace- oder Anwendungs-Resource-Principal verwenden.

Sie können Parameter in eine REST-Aufgabe aufnehmen, damit Sie die Aufgabe in verschiedenen Laufzeitsituationen verwenden können.

Sie können Parameter für die folgenden Teile der REST-Anforderung in einer REST-Aufgabe verwenden:

• Abschnitte der REST-Ausführungs-URL, Polling-URL oder Beendigungs-URL. In Data Integration werden die parametrisierten Variablenbereiche der URL als URL-Parameter bezeichnet. Siehe HTTP-Methode, URL und URL-Parameter konfigurieren.
• Wert eines Headers in der Anforderung. Siehe Headerwert parametrisieren.
• Gesamter Anforderungsbody in einer POST- oder PUT-Anforderung. Siehe Anforderungsbody parametrisieren.
• Erfolgsbedingung, die die Kriterien für einen erfolgreichen Abschluss des REST-Aufrufs festlegt. Siehe Erfolgsbedingung parametrisieren.
• Abfragebedingung (anhand der Antwort geschrieben, die von der Abfrageanforderung zurückgegeben wird), die bestimmt, ob das Polling gestoppt oder fortgesetzt wird. Siehe Polling-Bedingung parametrisieren.