Führen Sie Ihre erste Abfrage über die Management-API durch

Rufen Sie die erste Seite der Veranstaltungen eines Kontos ab und durchlaufen Sie die Ergebnisse. In diesem Tutorial werden Daten gelesen, ohne dass Kontodatensätze geändert werden.

Bevor Sie beginnen

Erfragen Sie den API-Ursprung Ihrer Bereitstellung, z. B. https://<api-host>, beim Support. Die Dokumentationswebsite ist nicht unbedingt der API-Host.
Beantragen Sie eine dedizierte Management-Zugangsberechtigung bei events:read. Die Verwaltung der Zugangsberechtigungen erfolgt ausschließlich durch den Support; befolgen Sie die Anweisungen unter API-Zugriff beantragen.
Verwenden Sie einen HTTP-Client, der JSON senden kann, oder installieren Sie für das Beispiel curl und jq.

Speichern Sie das Token in einem serverseitigen Secret-Manager. Es identifiziert das Konto bereits; lassen Sie X-Tenant-Domain weg.

1. Senden Sie die Anfrage

Legen Sie KORONA_EVENT_API_ORIGIN und KORONA_EVENT_MANAGEMENT_TOKEN in Ihrer Prozessumgebung mithilfe Ihres API-Hosts und Ihres Secret-Managers fest. Speichern Sie diesen Vorgang als management-events.graphql:

graphql

query EventIndex($first: Int, $after: String, $updatedSince: DateTime) {
  events(first: $first, after: $after, updatedSince: $updatedSince) {
    nodes {
      id
      name
      number
      updatedAt
      discardedAt
      tombstone
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Senden Sie die Datei mit einer Seitengröße von 100 und ohne Cursor oder Datumsfilter:

jq -n --rawfile query management-events.graphql   '{query: $query, variables: {first: 100, after: null, updatedSince: null}}'   > management-request.json

curl --fail-with-body -sS   "$KORONA_EVENT_API_ORIGIN/api/graphql/management/v1"   -H 'Content-Type: application/json'   -H "Authorization: Bearer $KORONA_EVENT_MANAGEMENT_TOKEN"   --data-binary @management-request.json > management-response.json

jq . management-response.json

2. Lesen Sie das Ergebnis ab

Eine Antwort hat folgende Struktur; Bezeichner, Namen, Zeitstempel, Cursor und die Anzahl der Datensätze hängen von Ihrem Konto ab:

json

{
  "data": {
    "events": {
      "nodes": [
        {
          "id": "event-id",
          "name": "Evening tour",
          "number": "E-1001",
          "updatedAt": "2026-10-18T08:30:00.000000Z",
          "discardedAt": null,
          "tombstone": false
        }
      ],
      "pageInfo": { "endCursor": "opaque-cursor", "hasNextPage": false }
    }
  }
}

Überprüfen Sie den HTTP-Status und den obersten Eintrag errors, bevor Sie die Seite akzeptieren. Ein HTTP-Status 200 kann dennoch GraphQL-Fehler enthalten. Ein leeres nodes-Array mit hasNextPage: false stellt ein erfolgreiches, leeres Ergebnis dar. name und number können den Wert „null“ annehmen.

3. Rufen Sie die nächste Seite ab

Wenn hasNextPage wahr ist, kopieren Sie den genau zurückgegebenen Wert von endCursor in das Feld variables.after der nächsten Anfrage. Behalten Sie dieselbe Abfrage, Seitengröße und denselben Wert für updatedSince bei. Wiederholen Sie diesen Vorgang, bis hasNextPage auf „false“ gesetzt ist. Senden Sie den oben genannten Beispielwert für opaque-cursor nicht.

Bei der Abfrage von 100 Datensätzen wird höchstens eine Seite abgerufen, nicht das gesamte Konto. Befolgen Sie die Anleitung unter Synchronisierung von Management-API-Datensätzen, um alle Seiten zu verarbeiten und einen sicheren Zwischenstand zu speichern.

Fehlerbehebung

Reaktion oder Symptom	Aktion
HTTP 401 mit `Unauthorized`	Überprüfen Sie den Endpunkt und das Token; bitten Sie den Support, die Gültigkeitsdauer oder einen eventuellen Widerruf zu überprüfen. Entfernen Sie einen konfliktverursachenden Mandanten-Header.
GraphQL `Not authorized`	Beantragen Sie eine Berechtigung mit dem für die ausgewählte Sammlung erforderlichen Berechtigungsbereich.
GraphQL `Invalid cursor`	Starten Sie die Ausführung ab dem gespeicherten Zeitstempel mit `after: null` neu; verwenden Sie zur Fortsetzung ausschließlich einen zurückgegebenen Cursor.
HTTP 429	Warten Sie mindestens das Intervall `Retry-After` ab und versuchen Sie es dann erneut mit Backoff und Jitter.
Ein Feld für eine Bestellung oder einen Bericht ist unbekannt	Befolgen Sie die Anleitung zu den detaillierten Daten; verwenden Sie das „Management v1“-Schema und Zugangsdaten mit den erforderlichen Berechtigungsbereichen.