Ressourcen · 86
API-Paginierung: Exporte ohne fehlende oder doppelte Datensätze
Reihenfolge, Token, Berechtigungen und Wiederaufnahme bei veränderlichen Sammlungen festlegen.
Aktualisiert · 8 min
Wozu dieser Leitfaden beiträgt
- Reihenfolge und Umfang festlegen
- Token als Fortsetzung behandeln
- Ende aus dem Vertrag ableiten
- Nach Fehlern fortsetzen
- Ergebnis abgleichen
Kurzcheck
- Bedeutet eine leere Seite das Ende?
- Kann ein Cursor Zugriffsrechte verleihen?
- Verhindert Deduplizierung fehlende Datensätze?
Schritt-für-Schritt-Anleitung
- 1
Reihenfolge und Umfang festlegen
Dokumentieren Sie Filter, Reihenfolge und einen Schlüssel zur eindeutigen Sortierung. Ein Zeitstempel genügt nicht immer, wenn mehrere Objekte ihn teilen. Entscheiden Sie zwischen laufender Sammlung und festem Datenstand. Versprechen Sie keine unveränderliche Sicht ohne entsprechende Anbietergarantie.
Ergebnis: Vertrag für Reihenfolge und Konsistenz.
- 2
Token als Fortsetzung behandeln
AIP-158 sieht opake Token vor und trennt Paginierung von Berechtigung: Ein Token gewährt keinen Zugriff. Prüfen Sie Identität und Rechte bei jeder Anfrage. Behalten Sie vertraglich gebundene Parameter bei und behandeln Sie Ablauf oder Ungültigkeit ausdrücklich.
Ergebnis: gültige, abgelaufene und unberechtigte Tokenfälle.
- 3
Ende aus dem Vertrag ableiten
Nehmen Sie nicht an, dass eine kurze Seite die letzte ist. Eine API kann weniger Einträge und trotzdem eine Fortsetzung liefern. Nach AIP-158 kennzeichnet ein leeres next_page_token das Ende; passen Sie den Client an den tatsächlichen Anbieter an. Erkennen Sie wiederholte Token ohne Fortschritt.
Ergebnis: Tests für Abschluss und Schleifen.
- 4
Nach Fehlern fortsetzen
Speichern Sie die Fortsetzung nach dauerhafter Ablage des Stapels. Entfernen Sie Duplikate anhand stabiler Kennungen und trennen Sie Wiederaufnahmestand von angezeigten Summen. Bei abgelaufenem Datenstand starten Sie neu oder gleichen nach festen Regeln ab; verbinden Sie nicht unbemerkt unterschiedliche Zustände.
Ergebnis: Prüfpunkt und Ausfallszenario.
- 5
Ergebnis abgleichen
Vergleichen Sie eindeutige Kennungen, Ausschlüsse, Zustände und mögliche Referenzsummen zum gleichen Stichtag. Testen Sie Anlage, Änderung und Löschung während des Lesens. Eine passende Anzahl beweist nicht die richtigen Objekte. Schützen Sie Dateien und Protokolle entsprechend ihrer Daten.
Ergebnis: Exportmanifest und dokumentierte Unterschiede.
Eine wiederaufnehmbare paginierte Abfrage
Bei einem Vertrag nach dem AIP-158-Muster bestimmt die Fortsetzung den nächsten Schritt. Eine kurze Seite beweist keinen Abschluss.
Abfrage festlegen
Filter, Reihenfolge, Parameter und berechtigte Identität bewahren.
Stapel speichern
Objekte und Kennungen dauerhaft ablegen.
Fortsetzung folgen
Ein vorhandenes Token führt zur nächsten Anfrage mit gebundenen Parametern.
Am Ende abgleichen
Bei leerem abschließendem Token Ausschlüsse, Referenzzustand und Abdeckung prüfen.
Fiktives Beispiel: Nach Stapelspeicherung fällt die Verbindung aus. Wiederaufnahme nutzt den Prüfpunkt und prüft schon verarbeitete Kennungen.
Nachvollziehbarer Abnahmefall
Fiktives Beispiel: Diese Daten beschreiben keine Kunden oder beobachteten Ergebnisse.
Falldaten anzeigen
{
"page_1_ids": [
"A",
"B"
],
"page_2_ids": [
"B",
"C"
],
"next_cursor": "c2",
"empty_page_has_next_cursor": true
}Erwartete Entscheidung
B wiederholt sich. Identitäten prüfen und Cursor auch nach einer leeren Seite weiterverfolgen.
Prüfverfahren
- Filter, stabile Ordnung und Objektidentität festlegen.
- Duplikat und leere Seite mit Cursor testen.
- Kennungen und tatsächliche Endbedingung aufbewahren. Vergleichen Sie empfangene Objekte und eindeutige Kennungen; markieren Sie wiederholte Cursor, ohne eine leere Seite mit Fortsetzung als Ende zu behandeln.
Wiederverwendbares Arbeitsblatt
Ergänzen Sie Ihre autorisierten Beobachtungen. Bei diesen Feldern handelt es sich um eine Arbeitsvorlage, nicht um beobachtete Ergebnisse.
| Feld | Zu erfassende Informationen |
|---|---|
| Sammlung | Filter, Reihenfolge, eindeutiger Sortierschlüssel und Garantien |
| Fortsetzung | Token, gebundene Parameter, Ablauf und Ende |
| Wiederaufnahme | Dauerhafter Stapel, eindeutige Kennungen und Prüfpunkt |
| Ergebnis | Manifest, Ausschlüsse, Stichtag und Unterschiede |
Fiktives Arbeitsbeispiel
Beispielhafte Situation
Fiktives Beispiel: Während eines Offset-Exports werden Produkte hinzugefügt und ein Datensatz verschiebt sich zwischen Seiten.
Entscheidung und erwartete Beweise
Der Test findet ein Duplikat und ein fehlendes Produkt; das Team nutzt einen verfügbaren Snapshot oder dokumentiert eine laufende Abfrage mit Abgleich.
Unterscheiden Sie die Mechanismen
| Mechanismus | Zweck | Überprüfung oder Einschränkung |
|---|---|---|
| Offset | Numerische Position ansteuern | Einfügungen können Positionen verschieben |
| Cursor | Von einem Lesemarker fortsetzen | Garantiert keinen festen Datenstand |
| Snapshot | Referenzzustand festlegen | Gültigkeitsdauer und Kosten prüfen |
Managementindikatoren
| Indikator | Was es misst | Erste Aktion |
|---|---|---|
| Eindeutige Kennungen | Unterschiedliche exportierte Objekte | Mit gleicher Referenz vergleichen |
| Fortschritt | Tatsächlich fortschreitende Token und Stapel | Schleifen beenden und untersuchen |
| Geprüfte Abdeckung | Mit Referenzzustand abgeglichene Objekte | Menge nicht mit Vollständigkeit gleichsetzen |
Häufige Fallstricke
- Einfügungen können Positionen verschieben
- Garantiert keinen festen Datenstand
- Gültigkeitsdauer und Kosten prüfen
Häufig gestellte Fragen
Bedeutet eine leere Seite das Ende?
Prüfen Sie Vertrag und Fortsetzungstoken. Die Seitengröße allein darf nicht entscheiden.
Kann ein Cursor Zugriffsrechte verleihen?
Nein. Der Server prüft Rechte unabhängig vom Paginierungstoken.
Verhindert Deduplizierung fehlende Datensätze?
Nein. Sie entfernt Wiederholungen, aber findet nie gelesene Objekte nicht. Prüfen Sie stabile Reihenfolge und Änderungen.
Paginierung: Konsistenz und Wiederaufnahme
Ausführliche Hinweise stehen in dieser Ausgabe auf Englisch zur Verfügung.
Reaching every page does not prove a coherent collection
A paginated collection needs an object order, continuation rules and a reconciliation reference. An advancing cursor can miss a row whose key changes; a correct unique-ID count can mix revisions. This exercise makes those differences checkable on five fictional objects.
Offline simulation: no API request, database or export file is created. Objects A–E, TRAIN tokens and snapshot S1 are teaching fixtures. Results describe this model and guarantee neither provider behavior nor coverage of a real collection.
Initial data: three objects share one timestamp
| Identifier | updated_at in UTC | Revision |
|---|---|---|
| A | 2026-10-22T10:00:00Z | 1 |
| B | 2026-10-22T10:00:00Z | 1 |
| C | 2026-10-22T10:00:00Z | 1 |
| D | 2026-10-22T10:01:00Z | 1 |
| E | 2026-10-22T10:02:00Z | 1 |
Ascending (updated_at, id), maximum page size 2, unique A–E IDs and non-null sort fields. Dates use equal precision. Production contracts also need types, collation and NULL handling; the word “cursor” supplies none of those assumptions.
Five computed reads and their references
These five runs model query-boundary reads: a query returning no rows ends each local run. A remote API’s completion rule is a separate contract; the continuation chain below does not stop at an empty page.
P1 · Timestamp alone leaves C behind
After A and B, updated_at > 10:00 skips C because it shares their timestamp. The ordering includes an ID tie-breaker, but the continuation condition omits it.
Reconciliation reference: Unchanged initial dataset
| Page and collection read | Received objects | Post-page boundary |
|---|---|---|
| 1 · Live collection at this read | A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z | 2026-10-22T10:00:00Z |
| 2 · Live collection at this read | D/r1 · 2026-10-22T10:01:00Z ; E/r1 · 2026-10-22T10:02:00Z | 2026-10-22T10:02:00Z |
| 3 · Live collection at this read | None | End observed in the model |
- Received rows
- 4
- Unique identifiers
- 4
- Identifiers missing from the reference
- C
- Repeated identifiers
- None
- Identifiers received under multiple revisions
- None
Four rows arrive and C is missing. A correct batch size does not repair an incomplete boundary.
P2 · Timestamp/ID pair on a stable collection
The boundary retains the last object’s timestamp and ID. After (10:00, B), C remains greater in this order. All five objects are read once in this stable dataset.
Reconciliation reference: Unchanged initial dataset
| Page and collection read | Received objects | Post-page boundary |
|---|---|---|
| 1 · Live collection at this read | A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z | 2026-10-22T10:00:00Z / B |
| 2 · Live collection at this read | C/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z | 2026-10-22T10:01:00Z / D |
| 3 · Live collection at this read | E/r1 · 2026-10-22T10:02:00Z | 2026-10-22T10:02:00Z / E |
| 4 · Live collection at this read | None | End observed in the model |
- Received rows
- 5
- Unique identifiers
- 5
- Identifiers missing from the reference
- None
- Repeated identifiers
- None
- Identifiers received under multiple revisions
- None
This result depends on an unchanged collection and total order. It promises no frozen view for a live API.
P3 · A moves forward and returns with a new revision
After page one, A changes from 10:00/r1 to 10:03/r2. The pair cursor advances but encounters A again.
Reconciliation reference: Final live collection
| Page and collection read | Received objects | Post-page boundary |
|---|---|---|
| 1 · Live collection at this read | A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z | 2026-10-22T10:00:00Z / B |
| 2 · Live collection at this read | C/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z | 2026-10-22T10:01:00Z / D |
| 3 · Live collection at this read | E/r1 · 2026-10-22T10:02:00Z ; A/r2 · 2026-10-22T10:03:00Z | 2026-10-22T10:03:00Z / A |
| 4 · Live collection at this read | None | End observed in the model |
- Received rows
- 6
- Unique identifiers
- 5
- Identifiers missing from the reference
- None
- Repeated identifiers
- A
- Identifiers received under multiple revisions
- A
Six rows and five unique IDs arrive. A occurs as revisions 1 and 2. ID deduplication alone does not establish temporal consistency of values; revision handling needs an explicit policy.
P4 · C moves behind the cursor
After page one, C changes from 10:00/r1 to 09:59/r2. Its new key falls below the boundary already passed.
Reconciliation reference: Final live collection
| Page and collection read | Received objects | Post-page boundary |
|---|---|---|
| 1 · Live collection at this read | A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z | 2026-10-22T10:00:00Z / B |
| 2 · Live collection at this read | D/r1 · 2026-10-22T10:01:00Z ; E/r1 · 2026-10-22T10:02:00Z | 2026-10-22T10:02:00Z / E |
| 3 · Live collection at this read | None | End observed in the model |
- Received rows
- 4
- Unique identifiers
- 4
- Identifiers missing from the reference
- C
- Repeated identifiers
- None
- Identifiers received under multiple revisions
- None
C is missing despite the complete sorting pair. A mutable sort key needs a consistency strategy beyond a unique tie-breaker.
P5 · Reading S1 retains S1 identities and values
A moves forward and C backward in the live collection, but every page in this run reads the exercise’s immutable S1 copy.
Reconciliation reference: Fictional snapshot S1
| Page and collection read | Received objects | Post-page boundary |
|---|---|---|
| 1 · Fictional snapshot S1 | A/r1 · 2026-10-22T10:00:00Z ; B/r1 · 2026-10-22T10:00:00Z | 2026-10-22T10:00:00Z / B |
| 2 · Fictional snapshot S1 | C/r1 · 2026-10-22T10:00:00Z ; D/r1 · 2026-10-22T10:01:00Z | 2026-10-22T10:01:00Z / D |
| 3 · Fictional snapshot S1 | E/r1 · 2026-10-22T10:02:00Z | 2026-10-22T10:02:00Z / E |
| 4 · Fictional snapshot S1 | None | End observed in the model |
- Received rows
- 5
- Unique identifiers
- 5
- Identifiers missing from the reference
- None
- Repeated identifiers
- None
- Identifiers received under multiple revisions
- None
All five revision-1 objects arrive once. S1 is the reconciliation reference; the final live state can differ. An opaque token alone does not establish that a provider implements this snapshot.
A snapshot needs a contract separate from the cursor
A sorting pair defines a boundary; a snapshot defines the objects and values visible during reading. PostgreSQL 18 distinguishes per-command Read Committed views from a Repeatable Read transaction view. An API spanning requests needs to explain its own mechanism and availability period. This exercise opens no transaction and does not recommend indefinitely retaining a production transaction.
An empty page can still have a next page
Under AIP-158, a response can return fewer objects than requested, including zero, without being final. An empty next_page_token signals completion. The TRAIN labels below are public teaching fixtures; clients must not infer a numeric position from them.
| Response | Sent token | Objects | Returned continuation |
|---|---|---|---|
| L1 | Start | A, B | TRAIN-CONT-1 |
| L2 | TRAIN-CONT-1 | None | TRAIN-CONT-2 |
| L3 | TRAIN-CONT-2 | C | TRAIN-CONT-3 |
| L4 | TRAIN-CONT-3 | D, E | End observed in the model |
Stop a repeated token without claiming completion
| Response | Sent token | Objects | Returned continuation |
|---|---|---|---|
| X1 | Start | A, B | TRAIN-LOOP |
| X2 | TRAIN-LOOP | None | TRAIN-LOOP |
Stop: repeated continuation
The second X response repeats the token already used. The teaching client stops this lack of progress. A real API client also needs bounds on calls, time, memory and retries: a changed token alone does not establish useful progress.
Nine continuation requests: context and permissions
The model binds a token to parent, filter, order and S1. Page size can change under AIP-158’s explicit exception. server_authorized and snapshot_available are server-side facts supplied by the fixture, not authoritative client parameters. Fictional expiry is 22 October 2026 at 13:00 UTC, an exclusive boundary.
C01 · Same context and current permission
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Continuation admissible in the profile
Continuation is admissible in this profile; permission checks still apply to returned objects.
C02 · Only page size changes
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 1,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Continuation admissible in the profile
Changing 2 to 1 does not by itself break this pagination context. Do not assume a provider with another contract follows the same rule.
C03 · Different parent
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-b",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Reject: different read context
A token must not become a bridge into a different collection parent.
C04 · Different filter
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=archived",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Reject: different read context
Reusing a token after changing filters would mix two different reads.
C05 · Different order
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Reject: different read context
A boundary created for one order must not silently acquire a different interpretation.
C06 · Permission revoked
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": false,
"snapshot_available": true
}Reject: current permission absent
The token still exists but grants no permission. Earlier authorization does not authorize the current request.
C07 · Exact expiry instant
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T13:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Recover under policy: token expired
At 13:00:00Z the token is expired under this profile. Its lifetime is fictional and supplies no universal retention recommendation.
C08 · Snapshot unavailable
{
"token": "TRAIN-CONT-1",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": false
}Review: S1 reference unavailable
The profile refuses to silently concatenate S1 with a new view. Restart or reconcile under an explicit policy.
C09 · Unknown token
{
"token": "TRAIN-UNKNOWN",
"parent": "training/catalogue-a",
"filter": "state=active",
"order": "updated_at,id",
"page_size": 2,
"now": "2026-10-22T12:00:00Z",
"server_authorized": true,
"snapshot_available": true
}Reject: unknown token
The model accepts only tokens in its fictional registry; it does not decode received text and invent continuation semantics.
Two crash recoveries: the checkpoint changes coverage
S1 batches are A/B, C/D and E. In this in-memory model, “durable” represents a batch already confirmed in fictional local storage. This is no real persistence test. Local processing is idempotent by S1 ID; that does not guarantee an exactly-once external effect.
R1 · Checkpoint before retaining the batch
R1 records the next page before retaining A/B. A crash occurs between the operations; recovery skips A and B.
| Step | Simulated operation | Retained objects | Recorded next page |
|---|---|---|---|
| 1 | Record the next page · 2 | None | 2 |
| 2 | Crash; volatile memory lost | None | 2 |
| 3 | Resume at the recorded page | None | 2 |
| 4 | Retain the batch idempotently · 2 | C, D | 2 |
| 5 | Record the next page · 3 | C, D | 3 |
| 6 | Retain the batch idempotently · 3 | C, D, E | 3 |
| 7 | Record the next page · 4 | C, D, E | End observed in the model |
Identifiers missing from the reference: A, B
R2 · Batch retained before checkpoint
R2 retains A/B, then crashes before checkpointing. Recovery rereads A/B; the idempotent sink retains them once, then finishes S1.
| Step | Simulated operation | Retained objects | Recorded next page |
|---|---|---|---|
| 1 | Retain the batch idempotently · 1 | A, B | 1 |
| 2 | Crash; volatile memory lost | A, B | 1 |
| 3 | Resume at the recorded page | A, B | 1 |
| 4 | Retain the batch idempotently · 1 | A, B | 1 |
| 5 | Record the next page · 2 | A, B | 2 |
| 6 | Retain the batch idempotently · 2 | A, B, C, D | 2 |
| 7 | Record the next page · 3 | A, B, C, D | 3 |
| 8 | Retain the batch idempotently · 3 | A, B, C, D, E | 3 |
| 9 | Record the next page · 4 | A, B, C, D, E | End observed in the model |
Identifiers missing from the reference: None
When batch and checkpoint share a suitable local transaction, test their joint commit. Effects across systems need a recovery protocol and reconciliation; simply reordering two calls does not demonstrate distributed atomicity.
Six records for pagination acceptance checks
- Scope, filter, total order and rules for nullable or mutable keys.
- Consistency reference: live collection, identified snapshot or another documented contract.
- Received batches, IDs and revisions, with reconciliation differences.
- Handling of short/empty pages, repeated tokens and bounded resources.
- Confirmed recovery checkpoint, local deduplication and completed external effects.
- Current permission checks and handling of unavailable tokens or snapshots.
The five reads, nine requests and two recoveries are computed editorial counterexamples. AIP-158 applies only to the declared contract; actual guarantees must come from the provider. No client export, real completeness rate or database transaction is claimed.
Primary sources and scope
- Google · AIP-158 Pagination · Approved AIP · changelog includes 2025-07-08 · checked 2026-10-22
Short/empty pages · next_page_token · page_size exception · opacity · authorization · expiry - PostgreSQL 18 · LIMIT and OFFSET · Version 18 documentation · checked 2026-10-22
§7.6: predictable unique ORDER BY with pagination - PostgreSQL 18 · Row constructor comparison · Version 18 documentation · checked 2026-10-22
§9.25.5: left-to-right tuple comparison · NULL behavior - PostgreSQL 18 · Transaction isolation · Version 18 documentation · checked 2026-10-22
Read Committed per-command snapshots · Repeatable Read transaction snapshot - OWASP · API1:2023 Broken Object Level Authorization · API Security Top 10 · 2023 edition
Object-level permission checks for every applicable operation
Sources reviewed on
Offizielle Referenzen
Die Referenzen unterstützen die Methode. Passen Sie die Prüfungen an Ihren Kontext an; sie stellen keine Zertifizierung dar. Originalreferenztitel und Quelldokumente können in einer anderen Sprache verfasst sein.
Referenzen geprüft am .
