Pagination beim Lesen aus einer API in Jitterbit Studio verwalten

Einführung

Die meisten REST-APIs begrenzen die Anzahl der Datensätze, die in einer einzelnen Antwort zurückgegeben werden. Wenn ein Datensatz größer als dieses Limit ist, teilt die API die Ergebnisse auf mehrere Seiten auf und erwartet, dass der Aufrufer jede Seite nacheinander anfordert. Ohne Pagination-Unterstützung ruft ein Studio-Vorgang nur die erste Seite ab und verwirft den Rest stillschweigend.

Diese Anleitung behandelt den Seitennummern-Pagination-Ansatz, bei dem jede Anfrage einen page-Parameter enthält, der mit jedem Aufruf erhöht wird. Eine Notiz am Ende von Teil 2 beschreibt, wie man das Muster für cursor-basierte APIs anpasst.

Diese Anleitung setzt Vertrautheit mit der Konfiguration von HTTP v2-Verbindungen und -Aktivitäten voraus. Eine allgemeine Einführung finden Sie unter REST-API mit dem HTTP v2-Connector aufrufen.

Entwurfsmuster

Das Muster verwendet zwei Vorgänge:

• Fetch Page-Vorgang: Liest eine Seite aus der API und schreibt die Datensätze in das Ziel, wobei das Transformationsmuster verwendet wird:

  %%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[HTTP v2 GET-Aktivität] --> B[Transformation] --> C[Zielaktivität]

• Controller-Vorgang: Ein einzelner Skriptschritt, der eine Schleife durchführt, bis alle Seiten abgerufen sind.

Das Controller-Skript verwendet eine While-Schleife, die RunOperation für jeden Seite auf den Fetch Page-Vorgang aufruft. RunOperation wird standardmäßig synchron ausgeführt, sodass globale Variable, die innerhalb des Fetch Page-Vorgangs geändert werden (einschließlich des Signals, dass keine weiteren Seiten vorhanden sind), nach jedem Aufruf im Controller sichtbar sind.

Zwei globale Variablen koordinieren die Schleife:

• page: die aktuelle Seitennummer, die im Controller mit 1 initialisiert und nach jedem Abruf erhöht wird.
• has_more: ein Flag, das mit true initialisiert und von der Transformation auf false gesetzt wird, wenn die letzte Seite erkannt wird.

Teil 1: Den Fetch Page-Vorgang konfigurieren

Schritt 1: HTTP v2 GET-Aktivität konfigurieren

1. Ziehen Sie auf der Entwurfsfläche eine HTTP v2 GET-Aktivität aus einem vorhandenen Endpunkt auf die Leinwand, um den Fetch Page-Vorgang zu starten.

2. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Name: Geben Sie einen Namen wie Get Contacts Page ein.

4. Pfad: Geben Sie den API-Endpunkt-Pfad ein, z. B. /contacts.

5. Anfrageparameter: Klicken Sie auf das Plussymbol , um eine Zeile hinzuzufügen, und geben Sie Folgendes ein:

   • Name: page
   • Wert: $page

   Dadurch wird die globale Variable page bei jeder Anfrage als Abfrageparameter übergeben. Fügen Sie eine zweite Zeile mit Name per_page und einem festen Wert wie 100 hinzu, um die Anzahl der pro Seite zurückgegebenen Datensätze zu steuern.

6. Klicken Sie auf Weiter.

Schritt 2: Antwortsschema definieren

1. Wählen Sie Ja, neues Schema bereitstellen.

2. Geben Sie ein JSON-Schema ein, das das von der API zurückgegebene Records-Array und das Pagination-Metadatenfeld enthält. Das folgende Beispielschema stellt eine Antwort dar, die ein contacts-Array und ein total_pages-Feld enthält:

   {
     "type": "object",
     "properties": {
       "contacts": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "id": { "type": "string" },
             "name": { "type": "string" },
             "email": { "type": "string" }
           }
         }
       },
       "total_pages": { "type": "integer" }
     }
   }
   

   Passen Sie das Schema an die tatsächliche Antwortstruktur Ihrer API an.

3. Klicken Sie auf Weiter und dann auf Fertig.

Teil 2: Pagination-Status in der Transformation extrahieren

Die Transformation ordnet die Quellfelder der GET-Aktivität den Zielaktivitätsfeldern zu und verwendet ein Skript, um die globale Variable has_more basierend darauf zu aktualisieren, ob weitere Seiten vorhanden sind.

1. Öffnen Sie die Transformation, die die GET-Aktivität folgt.

2. Ordnen Sie jedes Feld aus dem Quell-contacts-Array den entsprechenden Zielfeldern zu.

3. Fügen Sie in der Transformation ein Skript auf Stammebene (außerhalb des Schleifenknotens) hinzu, das has_more basierend auf dem total_pages-Wert aus der Antwort festlegt:

$total_pages = Source.total_pages;
If($page >= $total_pages, $has_more = false);

Dieser Code liest den Wert total_pages aus der Antwort und setzt $has_more = false, wenn die aktuelle Seite die letzte ist.

If(Count(Source.contacts.id) < 100, $has_more = false);

$cursor = Source.next_cursor;
If($cursor == "", $has_more = false);

Teil 3: Controller-Skript schreiben

Die Controller-Operation enthält ein einzelnes Skript, das den Schleifenzustand initialisiert und die Fetch-Page-Operation wiederholt aufruft, bis alle Seiten verarbeitet wurden.

1. Erstellen Sie auf der Design-Leinwand eine neue Operation mit nur einem Script-Schritt.

2. Doppelklicken Sie auf das Skript, um den Editor zu öffnen, und geben Sie Folgendes ein:

   $page = 1;
   $has_more = true;
   
   While($has_more,
       If(!RunOperation("<TAG>operation:Fetch Page</TAG>"), RaiseError(GetLastError()));
       $page++;
   );
   

   Ersetzen Sie Fetch Page durch den genauen Namen der Fetch-Page-Operation.

3. Speichern Sie das Skript.

Wichtige Punkte zu diesem Skript:

• page und has_more sind globale Variablen, die die Fetch-Page-Operation bei jedem synchronen RunOperation-Aufruf erbt.
• Nach der Verarbeitung jeder Seite erhöht der Controller page, bevor die nächste Iteration startet.
• RaiseError(GetLastError()) stoppt die Schleife sofort und meldet den Fehler, wenn die Fetch-Page-Operation einen Fehler zurückgibt.
• RunOperation unterliegt auch einem separaten Limit auf Agent-Ebene für synchrone Aufrufe innerhalb einer einzelnen While-Schleife (standardmäßig 50). Wenn die API über 50 Seiten hinaus paginiert, erreicht diese Schleife dieses Limit, bevor has_more auf false gesetzt wird: RunOperation gibt false zurück, und RaiseError(GetLastError()) stoppt die Operation mit der Fehlermeldung des Limits, anstatt die Synchronisierung abzuschließen. Informationen zum Konfigurieren oder Überschreiben dieses Limits finden Sie in der Anmerkung unter RunOperation.

• Die While-Funktion erzwingt eine maximale Iterationszahl, die standardmäßig 50.000 beträgt. Für APIs mit sehr großen Datenmengen setzen Sie $jitterbit.scripting.while.max_iterations vor der Schleife auf ein geeignetes Limit:

  $jitterbit.scripting.while.max_iterations = 2000;
  $page = 1;
  $has_more = true;
  
  While($has_more,
      If(!RunOperation("<TAG>operation:Fetch Page</TAG>"), RaiseError(GetLastError()));
      $page++;
  );
  

Integration überprüfen

Stellen Sie die Controller-Operation bereit und führen Sie sie aus. Überprüfen Sie die Operationsprotokolle: Die Fetch-Page-Operation wird einmal pro Seite angezeigt, daher bestätigt die Anzahl der Protokolleinträge, wie viele Seiten abgerufen wurden. Überprüfen Sie, ob die Gesamtanzahl der Datensätze im Ziel dem vollständigen vom API erwarteten Datensatz entspricht.

Um die frühe Beendigung vor der Verarbeitung eines vollständigen Datensatzes zu testen, setzen Sie $jitterbit.scripting.while.max_iterations = 3 beim ersten Durchlauf im Controller-Skript. Dies begrenzt die Schleife auf drei Seiten und ermöglicht es Ihnen, zu bestätigen, dass die Seitenerhöhung, die Schema-Zuordnung und die has_more-Logik korrekt funktionieren, bevor Sie das Limit entfernen und gegen den vollständigen Datensatz ausführen.

Um automatische Wiederholungen hinzuzufügen, falls ein Seitenabruf fehlschlägt, lesen Sie Fehlgeschlagene Operation erneut versuchen. Anweisungen zum Erstellen von Abfragezeichenfolgen mit dynamischen Cursor- oder Filterwerten finden Sie unter Dynamische Abfragezeichenfolgen für REST-API-Aufrufe erstellen.