Pagination beim Lesen aus einer API in Jitterbit Studio verarbeiten

Einführung

Die meisten REST-APIs begrenzen die Anzahl der in einer einzelnen Antwort zurückgegebenen Datensätze. 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 Paginierungsunterstützung ruft ein Studio-Vorgang nur die erste Seite ab und verwirft den Rest stillschweigend.

Diese Anleitung behandelt den Seitennummern-Paginierungsansatz, bei dem jede Anfrage einen page-Parameter enthält, der sich mit jedem Aufruf erhöht. Eine Anmerkung 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 Eine REST-API mit dem HTTP v2-Connector aufrufen.

Designmuster

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:

  flowchart LR A[HTTP v2 GET-Aktivität] --> B[Transformation] --> C[Zielaktivität]

• Controller-Vorgang: Ein einzelner Skriptschritt, der eine Schleife durchläuft, bis alle Seiten abgerufen sind.

Das Controller-Skript verwendet eine While-Schleife, die RunOperation für den Fetch-Page-Vorgang für jede Seite aufruft. RunOperation wird standardmäßig synchron ausgeführt, daher sind globale Variablen-Änderungen, die im Fetch-Page-Vorgang vorgenommen werden (einschließlich des Signals, dass keine weiteren Seiten vorhanden sind), nach jedem Aufruf im Controller sichtbar.

Zwei globale Variablen koordinieren die Schleife:

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

Teil 1: Konfigurieren des Fetch-Page-Vorgangs

Schritt 1: Konfigurieren der HTTP v2 GET-Aktivität

1. Ziehen Sie auf der Designoberfläche eine HTTP v2 GET-Aktivität von einem vorhandenen Endpunkt auf die Oberfläche, 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-Endpunktpfad 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

   Dies übergibt die globale Variable page als Abfrageparameter bei jeder Anfrage. 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: Definieren des Antwortschemas

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 Paginierungs-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: Paginierungsstatus in der Transformation extrahieren

Die Transformation ordnet die Quellfelder aus 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 der 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 der Stammebene (außerhalb des Schleifenknotens) hinzu, das has_more basierend auf dem total_pages-Wert aus der Antwort setzt:

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

Dies 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-Canvas eine neue Operation, die nur einen Script-Schritt enthält.

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 beginnt.
• RaiseError(GetLastError()) stoppt die Schleife sofort und zeigt den Fehler an, 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 geht: RunOperation gibt false zurück, und RaiseError(GetLastError()) stoppt die Operation mit der Fehlermeldung des Limits, anstatt die Synchronisierung abzuschließen. Weitere Informationen zum Konfigurieren oder Überschreiben dieses Limits finden Sie in der Anmerkung unter RunOperation.

• Die While-Funktion erzwingt eine maximale Iterationsanzahl, 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 einen angemessenen Wert:

  $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 Datensatz entspricht, der von der API erwartet wird.

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

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