Synchronisierung von Management-API-Datensätzen

Erstellen Sie eine lokale Kopie, indem Sie jede Seite jeder erforderlichen „Management v1“-Sammlung einlesen. Bei späteren Durchläufen werden die Änderungen mit updatedSince abgerufen. Hierbei handelt es sich um einen Feed mit aktuellen Datensätzen, nicht um ein Prüfprotokoll aller zwischenzeitlichen Änderungen oder einen vollständigen Kontoexport.

Bevor Sie beginnen

Führen Sie den Management-Schnellstart durch. Wählen Sie die Sammlungen aus der Referenz aus und ermitteln Sie deren erforderliche Berechtigungsbereiche. Speichern Sie pro Konto und Sammlung einen Zeitstempel-Checkpoint.

Ihr Zielsystem muss „Upserts“ sowie die Deaktivierung oder Löschung anhand der Datensatz-ID unterstützen. Behalten Sie Zeitstempel und den „Tombstone“-Status bei, auch wenn Sie verworfene Datensätze vor Ihrer Anwendung verbergen.

1. Laden Sie die gesamte Sammlung

1. Erfassen Sie die Startzeit des Laufs in UTC als potenziellen Kontrollpunkt. Halten Sie die Uhr Ihres Workers synchronisiert und verwenden Sie bei späteren Läufen ein Überlappungsintervall.
2. Führen Sie beim ersten Laden eine Abfrage für eine Sammlung mit den Werten first: 100, after: null und ohne updatedSince durch.
3. Überprüfen Sie HTTP- und GraphQL-Fehler, bevor Sie eine Antwort verwenden.
4. Speichern Sie jeden Knoten. Bei tombstone: false fügen Sie den lokalen Datensatz ein oder aktualisieren Sie ihn. Bei tombstone: true entfernen Sie den Datensatz oder deaktivieren Sie ihn, wobei der Synchronisationszeitstempel erhalten bleibt.
5. Wenn hasNextPage auf „true“ gesetzt ist, fordern Sie die nächste Seite mit dem Wert von endCursor an. Belassen Sie alle anderen Argumente unverändert.
6. Nachdem die letzte Seite erfolgreich gespeichert wurde, speichern Sie den vorläufigen Prüfpunkt dauerhaft. Im Falle eines Fehlers belassen Sie den vorherigen Prüfpunkt unverändert.

Wiederholen Sie diesen Vorgang für jede Sammlung separat. Eine Berechtigung muss den Berechtigungsbereich jeder exportierten Sammlung umfassen. Für jede Sammlung ist ein eigener Paginierungsdurchlauf erforderlich.

2. Spätere Änderungen abrufen

Verwenden Sie denselben Vorgang wie im Schnellstart. Setzen Sie updatedSince auf den zuvor abgeschlossenen Prüfpunkt abzüglich des von Ihnen gewählten Überlappungsintervalls und beginnen Sie mit after: null:

{
  "first": 100,
  "after": null,
  "updatedSince": "2026-10-18T08:25:00Z"
}

Dies ist das variables-Objekt des Vorgangs, nicht der vollständige HTTP-Body. Blättern Sie durch jedes Ergebnis, bevor Sie den Kontrollpunkt auf die Startzeit dieses Durchlaufs verschieben. Verschieben Sie ihn nicht auf den Zeitstempel des letzten Datensatzes oder die Endzeit des Durchlaufs: Andernfalls könnten gleichzeitige Änderungen übersprungen werden. Ein leerer, abgeschlossener Durchlauf kann ebenfalls auf seine Startzeit verschoben werden.

Wählen Sie eine Überlappung, um erwartete Taktversätze und verzögerte Sichtbarkeit auszugleichen, und führen Sie regelmäßige Abgleiche durch, um die Vollständigkeitsanforderungen Ihrer Integration zu erfüllen. Verwenden Sie filter.updatedBefore, um einen Durchlauf bei Bedarf zu begrenzen. Die API verfügt über kein Snapshot-Token; die Paginierung über ein sich änderndes Konto hinweg stellt keinen transaktionalen Snapshot dar.

3. Speicherung und Wiederholungsversuche idempotent gestalten

Für jedes Konto, jede Sammlung und id:

• Wenden Sie Datensätze mit einem neueren updatedAt an, einschließlich Tombstones.
• Behandeln Sie eine identische Version als Wiederholung; erstellen Sie keinen weiteren Datensatz und wiederholen Sie keine nachgelagerten Nebenwirkungen.
• Vermeiden Sie es, eine neuere Version durch eine ältere aus einem sich überschneidenden oder wiederholten Durchlauf zu überschreiben.
• Wenden Sie eine neuere aktive Version an, falls ein zuvor verworfener Datensatz wiederhergestellt wird.

Gehen Sie nicht davon aus, dass Zeitstempel über alle Datensätze hinweg eindeutig sind. Der Server sortiert zudem nach ID, weshalb ein Zeitstempel allein den Cursor innerhalb eines Durchlaufs nicht ersetzen kann.

4. Einen fehlgeschlagenen Durchlauf wiederherstellen

Versuchen Sie es bei vorübergehenden Netzwerk- und Serverfehlern mit begrenztem Backoff erneut; beachten Sie bei HTTP 429 Retry-After. Versuchen Sie es erneut mit derselben Seite, solange der Lauf aktiv bleibt. Wenn Sie den Lauf neu starten, beginnen Sie mit after: null und dem Zeitstempel des zuvor abgeschlossenen Laufs abzüglich der Überlappungszeit. Das erneute Abspielen bereits gespeicherter Seiten ist sicher, sofern der Speicher idempotent ist.

Ein Cursor dient ausschließlich dazu, den aktuellen Erfassungslauf fortzusetzen. Dekodieren Sie ihn nicht, verwenden Sie ihn nicht für mehrere Erfassungen und speichern Sie ihn nicht als Checkpoint für den nächsten inkrementellen Lauf. Sollte ein Cursor ungültig sein, starten Sie den Vorgang anhand des Zeitstempels neu, anstatt einen neuen Cursor zu erstellen.

Vollständigkeitsgrenzen

„Tombstones“ beziehen sich auf verworfene Datensätze, die von diesen Sammlungen zurückgegeben werden. Sie stellen keine Garantie für ein dauerhaftes Löschprotokoll dar. Der Feed gibt nicht jede historische Version, Änderungen an zugehörigen Datensätzen oder eine Datenbanksicherung preis. Exportieren Sie untergeordnete Sammlungen separat: Eine geänderte Zahlung oder Anwesenheit garantiert nicht, dass sich der Zeitstempel des übergeordneten Auftrags ändert. Datensätze ohne Unterstützung für die Verwerfung geben stets tombstone: false zurück; gleichen Sie vollständige ID-Sätze ab, um endgültige Löschungen zu erkennen. Behalten Sie beim Vergleich von Versionen die Mikrosekunden des Zeitstempels bei. Verwenden Sie Kontodaten und Berichte abfragen, um eine umfassendere Integration zu planen.