Cloudflare SQL API introspection’ı güncelledi: JSON alanlarını tahmin yürütmeden keşfedin

Bir analitik veri kümesinin şemasında attributes adlı bir JSON sütunu bulunuyor, ancak bu sütundaki anahtarlar hesap verilerine göre değişiyorsa Cloudflare artık bunları introspection aracılığıyla keşfetmenizi sağlıyor. 27 Ekim 2026 tarihli güncelleme, include_attributes=true parametresini ekledi: Yanıt, hesap verilerinde önceki yedi gün içinde bulunan anahtarları ve türleri listeliyor.

Bu, geliştiriciler için somut bir sorunu çözüyor: Bir filtre oluşturmadan önce seçilen veri kümesinde hangi alanların gerçekten bulunduğunu kontrol edebilirsiniz. Eski include_custom_attributes ve custom_attributes adları şimdilik çalışmaya devam ediyor, ancak Cloudflare bunları kullanımdan kaldırılacak olarak işaretledi. Yeni entegrasyonlar güncellenmiş SQL API introspection özelliğini temel almalı.

Introspection tam olarak ne döndürüyor?

Bazı Cloudflare Analytics veri kümeleri, attributes sütununda ek anahtar-değer çiftleri saklar. Yeni parametreyle çalışan introspection, yedi günlük verileri temel alarak anahtarları ve türlerini belirler ve bu bilgileri veri kümesi nesnesinin attributes alanında döndürür. Hesaptaki yakın tarihli kayıtlardan çıkarılan bu şema, SQL sorgusu hazırlamaya yardımcı olur.

Cloudflare’ın resmî örneğinde /client/v4/analytics/sql/introspection yolu kullanılıyor; hesap kimliği ve events.httpRequests veri kümesi adı gönderiliyor, ayrıca öznitelik keşfi etkinleştiriliyor:

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"

Çalıştırmadan önce CLOUDFLARE_API_TOKEN ve CLOUDFLARE_ACCOUNT_TAG değişkenlerini ortamda tanımlayın. Token, bearer kimlik bilgisi olarak gönderilir; örnekteki değişken adları Cloudflare’a ait ayrı parametreler değil, komutun yerel ayarlarıdır.

Bulunan anahtardan sorguya

Introspection işleminden sonra, ilgili veri kümesinin açıklamasındaki attributes alanını kontrol edip listelenen anahtarlardan birini seçin. Cloudflare, JSON sütunundaki bir anahtara doğrudan erişim örneği olarak attributes['http.method'] ifadesini gösteriyor. Filtrenizde olay adından tahmin ettiğiniz bir adı değil, keşfedilen anahtarı kullanın.

Uygulanabilecek adımlar şöyle:

1. Gerekli veri kümesi için include_attributes=true ile introspection isteği gönderin.
2. Döndürülen attributes alanındaki anahtarları ve türleri, kontrol tarihini de ekleyerek kaydedin.
3. attributes['http.method'] gibi tam anahtar adını kullanarak sorgunuzu oluşturun.
4. Sorguyu kendi hesap verilerinizle test edin; şema veya gelen olayların niteliği değiştiğinde keşif işlemini tekrarlayın.

Kontrol tarihini kaydetmek, sonuçların yeniden üretilebilmesi açısından yararlıdır: Cloudflare öznitelikleri yedi günlük bir zaman aralığındaki verilerden çıkarır. Bu nedenle keşfedilen anahtarlar değişmez bir şemayı değil, yakın tarihli verileri yansıtır. Aradığınız anahtar bu zaman aralığında görülmemişse sonuçta bulunmaması, tek başına onun her koşulda kullanılamaz olduğunu göstermez.

Eski adlardan geçiş

Mevcut kodunuzda sorgu parametresi include_custom_attributes yerine include_attributes kullanın; yanıtı işlerken de custom_attributes alanını okumak yerine attributes alanını okuyun. Cloudflare, eski adların çalışmaya devam ettiğini belirtiyor; bu nedenle geçişi, entegrasyonu acilen düzeltmeniz gerekmeden ayrı olarak gerçekleştirebilirsiniz.

Güvenli bir geçiş için sözleşmenin iki bölümünü de kontrol edin: gönderilen sorgu parametresini ve yanıttaki alanın yolunu. Ardından aynı veri kümesinde isteği çalıştırıp anahtar listesini karşılaştırın. Böylece, isteğin yeni parametre adını kullanmasına karşın kodun yanıtın eski alanını beklemeye devam etmesi gibi yaygın bir geçiş hatasını yakalayabilirsiniz.

Analitik işlem hatları için sonuç

include_attributes=true, dinamik JSON alanlarını resmî introspection mekanizması üzerinden keşfedilebilir hâle getiriyor ve geliştiricilere anahtar adlarının yanı sıra türlerini de sunuyor. Yeni isteklerinizi ve ayrıştırıcılarınızı include_attributes parametresine ve yanıttaki attributes alanına geçirin, keşif tarihini kaydedin ve filtreleri gerçekten bulunan anahtarlara göre oluşturun.