Cloudflare met à jour l’introspection de son API SQL : découvrir les champs JSON sans deviner

Si le schéma d’un jeu de données analytiques contient une colonne JSON attributes dont les clés dépendent des données du compte, Cloudflare permet désormais de les découvrir par introspection. La mise à jour du 27 octobre 2026 a ajouté le paramètre include_attributes=true : la réponse énumère les clés et les types trouvés dans les données du compte au cours des sept jours précédents.

Pour les développeurs, cela répond à un besoin concret : avant de créer un filtre, ils peuvent vérifier quels champs figurent réellement dans le jeu de données choisi. Les anciens noms include_custom_attributes et custom_attributes fonctionnent encore, mais Cloudflare les a déclarés obsolètes. Les nouvelles intégrations devraient s’appuyer sur la nouvelle introspection de l’API SQL.

Ce que renvoie l’introspection

Certains jeux de données Cloudflare Analytics stockent des paires clé-valeur supplémentaires dans la colonne attributes. Grâce au nouveau paramètre, l’introspection détermine les clés et leurs types à partir des données des sept derniers jours, puis renvoie ces informations dans le champ attributes de l’objet du jeu de données. Ce schéma, déduit des enregistrements récents du compte, aide à préparer une requête SQL.

Dans son exemple officiel, Cloudflare utilise la route /client/v4/analytics/sql/introspection, transmet l’identifiant du compte et le nom du jeu de données events.httpRequests, et active la découverte des attributs :

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"

Avant de lancer la commande, définissez les variables CLOUDFLARE_API_TOKEN et CLOUDFLARE_ACCOUNT_TAG dans l’environnement. Le jeton est transmis comme justificatif d’authentification Bearer ; les noms de variables de l’exemple sont des paramètres locaux de la commande, et non des paramètres distincts de Cloudflare.

De la clé découverte à la requête

Après l’introspection, examinez le champ attributes dans la description du jeu de données voulu et choisissez une clé effectivement répertoriée. Cloudflare montre comment accéder précisément à une clé de la colonne JSON : attributes['http.method']. Dans votre filtre, utilisez le nom découvert plutôt qu’un nom supposé d’après celui de l’événement.

Voici une procédure pratique :

1. Interrogez l’introspection du jeu de données voulu avec include_attributes=true.
2. Enregistrez les clés et les types du champ attributes renvoyé, avec la date de vérification.
3. Construisez la requête en utilisant le nom exact de la clé, par exemple attributes['http.method'].
4. Testez la requête sur les données de votre compte et relancez la découverte lorsque le schéma ou la nature des événements entrants change.

La date de vérification facilite la reproductibilité : Cloudflare déduit les attributs à partir d’une fenêtre de sept jours. La liste des clés découvertes reflète donc les données récentes, et non un schéma immuable. Si une clé recherchée n’est pas apparue dans cette fenêtre, son absence du résultat ne permet pas, à elle seule, de conclure qu’elle est universellement indisponible.

Comment abandonner les anciens noms

Dans le code existant, remplacez le paramètre de requête include_custom_attributes par include_attributes, et la lecture du champ de réponse custom_attributes par celle de attributes. Cloudflare indique que les anciens noms restent fonctionnels ; la migration peut donc être effectuée sans devoir rétablir immédiatement une intégration défaillante.

Pour une transition sûre, vérifiez les deux parties du contrat : le paramètre de requête envoyé et le chemin d’accès au champ dans la réponse. Lancez ensuite la requête sur un même jeu de données et comparez la liste des clés. Ce test permet de repérer une erreur de migration fréquente : la requête utilise le nouveau nom de paramètre, mais le code attend encore l’ancien champ de réponse.

À retenir pour les pipelines analytiques

include_attributes=true permet de découvrir les champs JSON dynamiques à l’aide du mécanisme officiel d’introspection et fournit aux développeurs les types associés aux noms des clés. Mettez à jour les nouvelles requêtes et les analyseurs pour utiliser include_attributes et le champ de réponse attributes, consignez la date de découverte et créez vos filtres à partir des clés réellement trouvées.