Cloudflare aktualisiert die SQL-API-Introspektion: JSON-Felder ohne Rätselraten erkennen

Enthält das Schema eines Analysedatensatzes eine JSON-Spalte attributes, deren Schlüssel jedoch von den Kontodaten abhängen, können Sie diese nun über die Introspektion ermitteln. Mit dem Update vom 27. Oktober 2026 kam der Parameter include_attributes=true hinzu: Die Antwort listet Schlüssel und Typen auf, die in den Kontodaten der vorangegangenen sieben Tage gefunden wurden.

Für Entwickler löst dies ein konkretes Problem: Vor dem Erstellen eines Filters lässt sich prüfen, welche Felder im ausgewählten Datensatz tatsächlich vorkommen. Die alten Namen include_custom_attributes und custom_attributes funktionieren weiterhin, wurden von Cloudflare jedoch als veraltet gekennzeichnet. Neue Integrationen sollten auf der aktualisierten SQL-API-Introspektion aufbauen.

Was die Introspektion zurückgibt

Einige Cloudflare-Analytics-Datensätze speichern zusätzliche Schlüssel-Wert-Paare in der Spalte attributes. Mit dem neuen Parameter ermittelt die Introspektion anhand der Daten aus sieben Tagen die Schlüssel und ihre Typen und gibt die Informationen im Feld attributes des Datensatzobjekts zurück. Das aus aktuellen Kontoeinträgen abgeleitete Schema hilft bei der Vorbereitung einer SQL-Abfrage.

Im offiziellen Beispiel verwendet Cloudflare den Endpunkt /client/v4/analytics/sql/introspection, übergibt die Konto-ID und den Datensatznamen events.httpRequests und aktiviert die Erkennung von Attributen:

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
  --data-urlencode "dataset_name=events.httpRequests" \
  --data-urlencode "include_attributes=true"

Legen Sie vor dem Aufruf die Umgebungsvariablen CLOUDFLARE_API_TOKEN und CLOUDFLARE_ACCOUNT_TAG fest. Das Token wird als Bearer-Anmeldedaten übergeben; die im Beispiel verwendeten Variablennamen sind lokale Konfigurationen des Befehls und keine eigenständigen Cloudflare-Parameter.

Vom gefundenen Schlüssel zur Abfrage

Prüfen Sie nach der Introspektion das Feld attributes in der Beschreibung des gewünschten Datensatzes und wählen Sie einen tatsächlich aufgeführten Schlüssel aus. Cloudflare zeigt den exakten Zugriff auf einen Schlüssel der JSON-Spalte beispielhaft so: attributes['http.method']. Verwenden Sie im Filter den ermittelten Namen, statt ihn aus der Ereignisbezeichnung abzuleiten.

Der praktische Ablauf sieht so aus:

1. Rufen Sie die Introspektion für den gewünschten Datensatz mit include_attributes=true ab.
2. Speichern Sie die Schlüssel und Typen aus dem zurückgegebenen Feld attributes zusammen mit dem Prüfdatum.
3. Erstellen Sie die Abfrage mit dem exakten Schlüsselnamen, zum Beispiel attributes['http.method'].
4. Testen Sie die Abfrage mit den Daten Ihres Kontos und führen Sie die Ermittlung erneut aus, wenn sich das Schema oder die eingehenden Ereignisse ändern.

Das Prüfdatum ist für die Reproduzierbarkeit hilfreich: Cloudflare leitet die Attribute aus einem Sieben-Tage-Zeitraum ab. Die ermittelten Schlüssel spiegeln deshalb aktuelle Daten wider und kein unveränderliches Schema. Ist ein benötigter Schlüssel in diesem Zeitraum nicht vorgekommen, lässt sich aus seinem Fehlen im Ergebnis allein nicht schließen, dass er generell nicht verfügbar ist.

So wechseln Sie von den alten Namen

Ersetzen Sie im vorhandenen Code den Abfrageparameter include_custom_attributes durch include_attributes und lesen Sie statt des Antwortfelds custom_attributes das Feld attributes aus. Cloudflare zufolge funktionieren die bisherigen Namen weiterhin. Die Migration muss daher nicht als dringende Maßnahme zur Wiederherstellung einer Integration erfolgen.

Prüfen Sie für einen sicheren Wechsel beide Teile der Schnittstelle: den gesendeten Abfrageparameter und den Pfad zum Feld in der Antwort. Führen Sie die Abfrage anschließend mit demselben Datensatz aus und vergleichen Sie die Schlüssellisten. So erkennen Sie einen typischen Migrationsfehler: Die Abfrage verwendet bereits den neuen Parameternamen, der Code erwartet aber weiterhin das alte Antwortfeld.

Fazit für Analyse-Pipelines

include_attributes=true macht dynamische JSON-Felder über den offiziellen Introspektionsmechanismus auffindbar und liefert Entwicklern neben den Schlüsseln auch deren Typen. Stellen Sie neue Abfragen und Parser auf include_attributes und das Antwortfeld attributes um, speichern Sie das Ermittlungsdatum und erstellen Sie Filter anhand tatsächlich gefundener Schlüssel.