/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.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.apikey:secret oder secret:).
Setzen Sie BASE auf den regionalen Host der Organisation – siehe
Regionen.
Eine Liste durchlaufen
Laden SieLIVING_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 einestype-Filters auf Seite zwei –, wird ein 400 mit dem Code
invalid_request für den Parameter page_token zurückgegeben:
400 Invalid request
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 bei429 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.
