Skip to main content
Jeder /v1-Listenendpunkt liefert dasselbe Envelope zurück und paginiert auf dieselbe Weise: tokenbasiert und nur vorwärts.

Das List-Envelope

string
Immer "list".
array
Die Seite mit Ressourcen in einer stabilen, deterministischen Reihenfolge.
string | null
Übergeben Sie diesen Wert in der nächsten Anfrage als page_token, um die folgende Seite abzurufen. null, wenn keine weiteren Ergebnisse vorhanden sind.
boolean
Gibt an, ob über diese Seite hinaus weitere Ergebnisse vorhanden sind.

Anfrageparameter

integer
Standard:"25"
Seitengröße. Eine ganze Zahl zwischen 1 und 500. Werte außerhalb dieses Bereichs liefern einen 400 mit dem Code invalid_request zurück.
string
Der next_page_token aus der vorherigen Antwort. Lassen Sie ihn für die erste Seite weg.
Es gibt keine Offset-Parameter, kein Zurückblättern zur vorherigen Seite und keine exakten Gesamtanzahlen. Um eine Sammlung zu zählen, müssen Sie sie durchlaufen.
Ausnahme: GET /v1/cohorts/{id}/members liefert höchstens 50 Zeilen pro Seite, auch wenn Sie einen höheren limit anfordern. has_more und next_page_token geben weiterhin den tatsächlichen Rest der Kohorte wieder.
Authentifizieren Sie sich mit einer der beiden Basic-Anmeldedatenformen – siehe Quickstart (apikey:secret oder secret:). Setzen Sie BASE auf den regionalen Host der Organisation – siehe Regionen.

Eine Liste durchlaufen

Laden Sie LIVING_SECURITY_API_KEY wie im Quickstart aus Ihrem Secret Manager. Dieses Beispiel benötigt entity:read; der Schlüssel, der für die Anleitung zur ersten Anfrage verwendet wurde, benötigt diese zusätzliche Berechtigung möglicherweise noch. Installieren Sie requests für Python oder jq für das Shell-Beispiel. Beide Beispiele legen eine Version fest, lassen Filter unverändert und lehnen Weiterleitungen ab. Sie brechen bei Fehlern und nach 1.000 Seiten ab, anstatt einen unvollständigen Durchlauf als abgeschlossen zu melden. Das Lese-Timeout von Python begrenzt die Inaktivität, nicht die gesamte Dauer des Jobs; legen Sie in Ihrer Integration ein Zeitlimit für den Job fest. Fordern Sie Seiten an, bis next_page_token den Wert null hat. Bevorzugen Sie limit=500 für Massenabfragen, damit Sie die Sammlung mit weniger Anfragen abdecken – siehe Ratenlimits.

Filter während der Paginierung stabil halten

Page-Tokens sind opake, signierte Cursor. Jedes Token ist an die Organisation, das authentifizierte Servicekonto, die Vertragsversion und den exakten Filtersatz der Anfrage gebunden, die es erzeugt hat. Wenn Sie eines davon mitten im Durchlauf ändern – zum Beispiel durch Hinzufügen eines type-Filters auf Seite zwei –, wird ein 400 mit dem Code invalid_request für den Parameter page_token zurückgegeben:
400 Invalid request
Um Filter zu ändern, beginnen Sie einen neuen Durchlauf ab der ersten Seite.
Behandeln Sie page_token als opaken String: Geben Sie ihn exakt so zurück, wie Sie ihn erhalten haben. Decodieren Sie Tokens nicht, speichern Sie sie nicht langfristig und erzeugen Sie sie nicht selbst – ihr internes Format kann sich jederzeit ohne Vorankündigung ändern.
Listenendpunkte weisen Abfrageparameter, die sie nicht unterstützen, mit einem 400 invalid_request zurück, der den Parameter benennt. Prüfen Sie in der Referenz des jeweiligen Endpunkts, welche Filter unterstützt werden.

Unterbrochene oder sich ändernde Sammlungen behandeln

Diese Beispiele wiederholen Fehler nicht automatisch. Beachten Sie bei 429 den Wert Retry-After und befolgen Sie die begrenzten Wiederholungsempfehlungen. Behalten Sie bei der Wiederholung einer Leseanfrage dieselbe Region, dasselbe Servicekonto, dieselbe Version, dieselben Filter und das zuletzt erfolgreich verarbeitete Page-Token bei. Ein Wechsel der Anmeldedaten gewährt keinen Zugriff: Jede Anfrage prüft weiterhin die aktuellen Berechtigungen. Ein mehrseitiger Lesevorgang ist kein Snapshot der Sammlung. Zeilen können sich ändern, während Sie die Sammlung durchlaufen. Verarbeiten Sie Ressourcen anhand ihrer stabilen id und gestalten Sie nachgelagerte Schreibvorgänge idempotent; nach einem Neustart kann eine Zeile erneut zurückgegeben werden. Wird ein Token abgelehnt, prüfen Sie den Fehler page_token und korrigieren Sie die Anfrage, bevor Sie mit Seite eins neu beginnen. Verwerfen Sie bereits verarbeitete Daten nicht stillschweigend und markieren Sie einen unterbrochenen Export nicht als abgeschlossen. Verwenden Sie für exakte Berichtssummen die entsprechende Berichtsressource, anstatt einen Live-Listendurchlauf als Snapshot zu behandeln.