Abschlusskriterien durch Polling angeben

Wenn Sie eine REST-Aufgabe ausführen, die einen REST-API-Vorgang mit langer Ausführungszeit aufruft, aktivieren Sie im Schritt Abschlusskriterien angeben das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren, um die Polling-Konfiguration für den Abschluss des REST-Aufrufs anzugeben.

Zusätzlich zur Erfolgsbedingung umfasst die Polling-Konfiguration eine Polling-REST-URL und -Bedingung sowie Werte für ein Polling-Intervall und einen Polling-Timeout.

Optional können Sie eine Beendigungskonfiguration angeben, um den API-Vorgang mit langer Ausführungszeit abzubrechen.

Um die API-Antwort aus dem Ausführungsschritt in der Polling- oder Beendigungskonfiguration zu verwenden, erstellen Sie Ausdrücke, und fügen Sie dann die benannten Ausdrücke in die Polling- und Beendigungs-URLs sowie die Polling- und Erfolgsbedingungen ein.

Bevor Sie Polling oder Beendigung konfigurieren, erstellen Sie die Ausdrücke, um die erforderlichen API-Antwortwerte abzurufen.

Siehe auch Polling bei Vorgängen mit langer Ausführungszeit.

Ausdrücke für das Polling hinzufügen

Mit Ausdrücken können Sie einer Variablen einen Wert oder Ausdruck zuweisen, den Sie dann bei der Konfiguration des Abschlusskriterienschritts verwenden können.

Erstellen Sie Ausdrücke, die die API-Antwort aus dem REST-Ausführungsschritt verwenden. Beim Erstellen des Ausdrucks geben Sie einen Namen an. Um den benannten Ausdruck in die Polling- oder Beendigungs-URL oder die Polling- oder Erfolgsbedingung aufzunehmen, verwenden Sie die Syntax #{expression_name}.

Beispiel: Wenn die REST-Aufgabe den API-Vorgang zum Erstellen eines Projekts mit einem bestimmten Projektnamen aufruft, kann die Polling-Anforderung den Projektschlüssel prüfen, um zu bestimmen, ob das Polling fortgesetzt oder gestoppt wird. Um den Projektschlüssel als Variable in der Polling-URL zu verwenden, erstellen Sie einen Ausdruck, der den Schlüssel aus der API-Payload-Antwort extrahiert und in einen Wert des Datentyps "Zeichenfolge" oder "JSON_TEXT" konvertiert.

Beachten Sie, dass ein Ausdruck, den Sie hier erstellen, nicht als REST-Aufgabenausgabe in anderen Operatoren verwendet werden kann, die der Aufgabe nachgelagert sind.

So fügen Sie einen Ausdruck hinzu:

  1. Aktivieren Sie auf der Seite REST-API-Details konfigurieren im Schritt Abschlusskriterien angeben das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren.
  2. Blenden Sie den Abschnitt Ausdrücke ein, und wählen Sie Ausdruck hinzufügen aus.
  3. Gehen Sie im Bereich Ausdruck hinzufügen im Abschnitt Informationen zu Ausdrücken wie folgt vor:
    1. Geben Sie im Feld ID einen Namen für den Ausdruck ein.
    2. Wählen Sie im Menü Datentyp einen Typ für diesen Ausdruck aus.
    3. Füllen Sie die Eigenschaftsfelder für den ausgewählten Datentyp aus. Beispiel: Geben Sie eine Länge für den Datentyp STRING ein.
  4. Im Abschnitt Expression Builder können Sie einen Ausdruck visuell erstellen, indem Sie auf eingehende Antwortausgaben, Parameter oder Funktionen doppelklicken oder diese ziehen, um den Ausdruck zu erstellen. Sie können den Ausdruck auch selbst manuell schreiben. Erstellen Sie einen Ausdruck, der die Ausgabe aus der Antwort der REST-Anforderung verwendet.
    • Eingehend: Sie können die Systemausgaben SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON und SYS.RESPONSE_STATUS verwenden.

    • Parameter: Sie können jeden Parameter verwenden, der im Geltungsbereich dieser REST-Aufgabe definiert ist. Siehe Parameter in einer REST-Aufgabe anzeigen und verwalten.

    • Funktionen: Sie können einfache Zeichenfolgen- und Operatordatenintegrationsfunktionen verwenden.

    Nicht alle Funktionen werden beim Erstellen des Ausdrucks unterstützt. Sie finden die unterstützten Funktionen in dieser Liste.

    Um JSON-Eigenschaftswerte aus dem API-Antwortbody zu extrahieren, verwenden Sie die json_path-Zeichenfolgenfunktion mit der eingehenden Antwortausgabe SYS.RESPONSE_PAYLOAD. Beispiel:

    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
  5. Wählen Sie Hinzufügen aus.
Ausdrücke beim Polling bearbeiten oder löschen

Sie können Ausdrücke, die Sie beim Polling erstellt haben, bearbeiten und löschen.

So bearbeiten oder löschen Sie einen Ausdruck:

  1. Klicken Sie auf der Seite REST-API-Details konfigurieren im Schritt Abschlusskriterien angeben auf den Abschnitt Ausdrücke.
  2. Suchen Sie in der Tabelle "Ausdrücke" den Ausdruck, den Sie bearbeiten oder löschen möchten.
  3. Klicken Sie im Menü "Aktionen" (Menü Aktionen) des Ausdrucks auf Bearbeiten oder Löschen.
    • nehmen Sie im Bereich Ausdruck bearbeiten die Änderungen vor, und wählen Sie dann Speichern aus.
    • Bestätigen sie im Dialogfeld Ausdruck löschen, dass sie den benannten Ausdruck löschen möchten, und wählen Sie dann Löschen aus.
HTTP-Methode und URL für Polling konfigurieren

Definieren Sie in einem API-Vorgang mit langer Ausführungszeit die HTTP-Methode und die URL, um den Status des REST-Aufrufs abzufragen.

Ähnlich wie bei der REST-URL im Ausführungsschritt können Sie Parameter mit der Syntax ${parameter_name} in die Polling-URL aufnehmen.

Außerdem können Sie benannte Ausdrücke mit der Syntax #{expression_name} aufnehmen. Erstellen Sie die Ausdrücke, die Sie benötigen, bevor Sie die Polling-URL konfigurieren.

So konfigurieren Sie die Polling-Methode und -URL:

  1. Aktivieren Sie auf der Seite REST-API-Details konfigurieren im Schritt Abschlusskriterien angeben das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren.
  2. Wählen Sie auf der Registerkarte Abfragen die HTTP-Methode für die Polling-URL aus.
  3. Geben Sie im Feld URL die vollständige URL ein, und drücken Sie die Eingabe.

    Wenn die Parametersyntax ${} für Teile der URL verwendet wird, werden diese Teile in URL-Parameter für die REST-Aufgabe konvertiert.

    Die Tabelle auf der Registerkarte URL-Parameter unter dem Feld "URL" wird mit den Parametern aktualisiert. Der Standarddatentyp für jeden URL-Parameter lautet "Zeichenfolge".

    Wenn Sie die URL durch Hinzufügen oder Entfernen von Parametersyntax bearbeiten, wird die URL-Parametertabelle entsprechend aktualisiert.

  4. Informationen zum Zuweisen eines Standardwerts zu einem Parameter finden Sie unter URL-Parameter konfigurieren.
  5. Um die Polling-URL mit den konfigurierten Parameterstandardwerten anzuzeigen oder auszublenden, wählen Sie Vorschau-URL anzeigen oder Vorschau-URL ausblenden aus.
  6. Informationen zum Hinzufügen eines Headers finden Sie unter Header hinzufügen und verwalten.
  7. Wenn ein Anforderungsbody erforderlich ist, finden Sie weitere Informationen unter Anforderungsbody angeben.
Polling-Bedingung angeben

Die Polling-Konfiguration umfasst eine Polling-Bedingung sowie Werte für ein Polling-Intervall und einen Polling-Timeout.

Die Polling-Bedingung ist ein Ausdruck, der bestimmt, ob das Polling gestoppt oder fortgesetzt wird. Wenn der Ausdruck "false" zurückgibt, wird das Polling gestoppt.

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.

So konfigurieren Sie die Polling-Bedingung:

  1. Aktivieren Sie auf der Seite REST-API-Details konfigurieren im Schritt Abschlusskriterien angeben das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren.
  2. Gehen Sie auf der Registerkarte Polling im Abschnitt Bedingungen folgendermaßen vor:
    1. Wählen Sie neben Polling-Bedingung Erstellen aus.
    2. Geben Sie im Bereich Polling-Bedingung erstellen einen Ausdruck ein, der die Ausgabe aus der Antwort der REST-Anforderung verwendet.

      Der Bedingungsausdruck kann die folgenden Elemente enthalten:

      • Eingehend: Eingehende Antwortausgaben (Beispiel: SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

      • Parameter: Parameter, die im Geltungsbereich dieser REST-Aufgabe definiert sind. Siehe Parameter in einer REST-Aufgabe anzeigen und verwalten.

      • Funktionen: Basisfunktionen für die Integration von Zeichenfolgen und Operatordaten. Mit der json_path-Funktion, die sich unter "Zeichenfolge" befindet, können Sie Eigenschaftswerte aus der Antwort mit JSONPath-Syntaxelementen im Format json_path(json_string, json_filter_path) extrahieren.

      Beispiel: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  3. Geben Sie im Abschnitt Bedingungen unter Polling-Bedingung einen Wert ein, und wählen Sie eine Maßeinheit für Polling-Intervall und Polling-Timeout aus.
    • Polling-Timeout: Die maximale Zeitspanne, während der wiederholtes Polling in der angegebenen Intervallrate ausgeführt werden darf. Der Timeoutwert muss größer/gleich 120 Sekunden, aber kleiner/gleich 30 Tage sein.
    • Abfrageintervall: Die Wartezeit vor dem Senden der nächsten Abfrageanforderung. Der Intervallwert muss größer/gleich 60 Sekunden und kleiner als der angegebene Timeoutwert sein.
  4. Um der Bedingung einen Aufgabenparameter zuzuweisen, wählen Sie Parameter zuweisen aus. Siehe Polling-Bedingung parametrisieren.
Polling-Bedingung parametrisieren

Nachdem Sie eine Polling-Bedingung hinzugefügt haben, können Sie der Bedingung einen Aufgabenparameter zuweisen.

So parametrisieren Sie die Polling-Bedingung in einer REST-Aufgabe:

  1. Gehen Sie auf der Seite REST-API-Details konfigurieren zum Schritt Abschlusskriterien angeben.
  2. Wählen Sie im Block Bedingungen neben Polling-Bedingung die Option Parameter zuweisen.
  3. Geben Sie im Bereich Parameter hinzufügen einen Namen für den Parameter ein, oder verwenden Sie den Standardwert.

    Der Parametername muss in der REST-Aufgabe eindeutig sein. Eine aktuelle Liste der Parameter in der Aufgabe finden Sie mit den Schritten unter Alle Parameter in einer REST-Aufgabe anzeigen.

  4. (Optional) Geben Sie eine Beschreibung ein, damit andere Benutzer den Zweck des Parameters erkennen können.
  5. Der Typ des Parameters lautet "Ausdruck". Diesen können Sie nicht ändern.
  6. Wählen Sie im Bedingungsbuilder den Standardbedingungsausdruck für diesen Parameter aus. Diese Standardbedingung wird zur Laufzeit verwendet, es sei denn, Sie ändern den Wert zu einem späteren Zeitpunkt (zur Entwurfs- oder Laufzeit).

    Der Bedingungsausdruck kann die folgenden Elemente enthalten:

    • Eingehend: Eingehende Antwortausgaben (Beispiel: SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parameter: Parameter, die im Geltungsbereich dieser REST-Aufgabe definiert sind. Siehe Parameter in einer REST-Aufgabe anzeigen und verwalten.

    • Funktionen: Basisfunktionen für die Integration von Zeichenfolgen und Operatordaten. Mit der json_path-Funktion, die sich unter "Zeichenfolge" befindet, können Sie Eigenschaftswerte aus der Antwort mit JSONPath-Syntaxelementen im Format json_path(json_string, json_filter_path) extrahieren.

    Beispiel: CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  7. Wählen Sie Hinzufügen aus.
    Der Parametername wird neben der Polling-Bedingung hinzugefügt.
Polling-Bedingungsparameter bearbeiten

Sie können die Beschreibung und den Standardwert des Aufgabenparameters für die Abfragebedingung ändern.

So bearbeiten Sie die parametrisierte Polling-Bedingung:

  1. Gehen Sie auf der Seite REST-API-Details konfigurieren zum Schritt Abschlusskriterien angeben.
  2. Wählen Sie im Block Bedingungen die Option Parameter bearbeiten aus.
  3. Im Bereich Parameter bearbeiten können Sie nur die Beschreibung und den Ausdruck für die Polling-Bedingung bearbeiten. Sie können die ID (Name) und den Datentyp nicht ändern.
  4. Wählen Sie Änderungen speichern aus.
Polling-Bedingungsparameter entfernen

Wenn Sie den Bedingungsparameter entfernen, wird nur die Verknüpfung des Parameters mit der für die REST-Aufgabe angegebenen Polling-Bedingung entfernt.

So heben Sie die Zuweisung des Parameters zur Polling-Bedingung auf:

  1. Gehen Sie auf der Seite REST-API-Details konfigurieren zum Schritt Abschlusskriterien angeben.
  2. Wählen Sie im Block Bedingungen die Option Parameter entfernen aus.
  3. Wählen Sie im Dialogfeld Parameter entfernen die Option Entfernen aus.

    Die Zuweisung des Parameters zur Polling-Bedingung wird aufgehoben. Der dem Parameter zugewiesene Bedingung wird zur Standard-Polling-Bedingung für die REST-Task.

    Hinweis

    Der Parameter wird nicht aus der REST-Aufgabe gelöscht. Informationen zum Löschen des Parameters finden Sie unter REST-Aufgabenparameter löschen.
HTTP-Methode und URL für Beendigung konfigurieren

Bei einer REST-Aufgabe, die einen REST-API-Vorgang mit langer Ausführungszeit aufruft, können Sie die REST-API-Details zum Beenden des Vorgangs mit langer Ausführungszeit angeben.

Definieren Sie auf der Registerkarte "Beendigung" die HTTP-Methode und die URL zum Beenden des REST-Aufrufs.

Ähnlich wie bei der Polling-URL können Sie Parameter und Ausdrücke mit der Syntax ${parameter_name} und #{expression_name} in die Beendigungs-URL aufnehmen. Erstellen Sie die Ausdrücke, die Sie benötigen, bevor Sie die Beendigungs-URL konfigurieren.

So konfigurieren Sie die Beendigungsmethode und -URL:

  1. Aktivieren Sie auf der Seite REST-API-Details konfigurieren im Schritt Abschlusskriterien angeben das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren.
  2. Wählen Sie auf der Registerkarte Beendigung die HTTP-Methode für die URL aus.
  3. Geben Sie im Feld URL die vollständige URL ein, und drücken Sie die Eingabe.

    Wenn die Parametersyntax ${} für Teile der URL verwendet wird, werden diese Teile in URL-Parameter für die REST-Aufgabe konvertiert.

    Die Tabelle auf der Registerkarte URL-Parameter unter dem Feld "URL" wird mit den Parametern aktualisiert. Der Standarddatentyp für jeden URL-Parameter lautet "Zeichenfolge".

    Wenn Sie die URL durch Hinzufügen oder Entfernen von Parametersyntax bearbeiten, wird die URL-Parametertabelle entsprechend aktualisiert.

  4. Informationen zum Zuweisen eines Standardwerts zu einem Parameter finden Sie unter URL-Parameter konfigurieren.
  5. Um die URL mit den konfigurierten Parameterstandardwerten anzuzeigen oder auszublenden, wählen Sie Vorschau-URL anzeigen oder Vorschau-URL ausblenden aus.
  6. Informationen zum Hinzufügen eines Headers finden Sie unter Header hinzufügen und verwalten.
  7. Wenn ein Anforderungsbody erforderlich ist, finden Sie weitere Informationen unter Anforderungsbody angeben.
Abschlusskriterien angeben (Erfolgsbedingung)

Die Erfolgsbedingung in einer REST-Aufgabe ist ein Ausdruck, der den erfolgreichen Abschluss des REST-API-Aufrufs bestimmt. Polling wird gestoppt, wenn die Erfolgsbedingung erfüllt ist.

Standardmäßig stellt Data Integration eine Erfolgsbedingung für eine REST-Aufgabe bereit. Die Standarderfolgsbedingung ist ein HTTP-Statuscode von 200 oder höher, aber kleiner als 300, der als der folgende Ausdruck geschrieben wird:

SYS.RESPONSE_STATUS >= 200 AND SYS.RESPONSE_STATUS < 300

Der Ausdruck für die Erfolgsbedingung referenziert die Ausgabe in der JSON-Antwort, die von der im Ausführungsschritt definierten REST-Anforderung empfangen wird.

Sie können die Standarderfolgsbedingung verwenden oder einen Bedingungsausdruck mit Systemausgaben oder extrahierten JSON-Eigenschaftenwerten aus der Antwort schreiben.

So bearbeiten Sie die Erfolgsbedingung:

  1. Gehen Sie auf der Seite REST-API-Details konfigurieren zum Schritt Abschlusskriterien angeben.
  2. Wenn die REST-API einen Vorgang mit langer Ausführungszeit aufruft, aktivieren Sie das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf konfigurieren.
  3. Wählen Sie im Block Bedingungen neben Erfolgsbedingung die Option Bearbeiten aus.
  4. Geben Sie im Bereich Erfolgsbedingung bearbeiten einen Ausdruck ein, der die Ausgabe aus der Antwort der REST-Anforderung verwendet.

    Der Bedingungsausdruck kann die folgenden Elemente enthalten:

    • Eingehend: Sie können die eingehenden Antwortausgaben verwenden (Beispiel: SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parameter: Sie können jeden Parameter verwenden, der im Geltungsbereich dieser REST-Aufgabe definiert ist. Siehe Parameter in einer REST-Aufgabe anzeigen und verwalten.

    • Funktionen: Sie können einfache Zeichenfolgen- und Operatordatenintegrationsfunktionen verwenden. Mit der json_path-Funktion, die sich unter "Zeichenfolge" befindet, können Sie Eigenschaftswerte aus der Antwort mit JSONPath-Syntaxelementen im Format json_path(json_string, json_filter_path) extrahieren.

      Beispiel: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

    Nicht alle Funktionen werden in einem Ausdruck für Erfolgsbedingungen unterstützt. Sie finden die unterstützten Funktionen in dieser Liste.

    (Bei Vorgängen mit langer Ausführungszeit) Wenn Sie das Kontrollkästchen Polling- und Beendigungsbedingung für einen REST-Aufruf ohne Warten konfigurieren aktiviert haben, ist die Erfolgsbedingung ein Ausdruck, der anhand der Antwort der Polling-Anforderung geschrieben wird. Sie können Ausdrücke erstellen, die die API-Antwort aus dem Ausführungsschritt verwenden, und dann die benannten Ausdrücke aufnehmen, um die Erfolgsbedingung zu erstellen.

  5. Um der Erfolgsbedingung einen Aufgabenparameter zuzuweisen, wählen Sie Parameter zuweisen aus. Siehe Erfolgsbedingung parametrisieren.