Cloudflare aktualizuje introspekci SQL API: jak odhalit pole JSON bez hádání

Pokud schéma analytické datové sady obsahuje sloupec JSON attributes, jehož klíče závisejí na datech účtu, Cloudflare nyní umožňuje tyto klíče zjistit prostřednictvím introspekce. Aktualizace z 27. října 2026 přidala parametr include_attributes=true: odpověď vypíše klíče a typy nalezené v datech účtu za předchozích sedm dní.

Vývojářům to pomáhá řešit konkrétní problém: před sestavením filtru mohou ověřit, která pole se ve vybrané datové sadě skutečně vyskytují. Starší názvy include_custom_attributes a custom_attributes zatím fungují, ale Cloudflare je označila za zastaralé. Nové integrace je vhodné stavět na aktualizované introspekci SQL API.

Co introspekce vrací

Některé datové sady Cloudflare Analytics ukládají další dvojice klíč–hodnota ve sloupci attributes. Introspekce s novým parametrem určuje klíče a jejich typy na základě dat za sedm dní a vrací tyto informace v poli attributes objektu datové sady. Jde o schéma odvozené z nedávných záznamů účtu, které pomáhá připravit SQL dotaz.

V oficiálním příkladu Cloudflare používá cestu /client/v4/analytics/sql/introspection, předává identifikátor účtu a název datové sady events.httpRequests a zapíná zjišťování atributů:

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"

Před spuštěním nastavte v prostředí proměnné CLOUDFLARE_API_TOKEN a CLOUDFLARE_ACCOUNT_TAG. Token se předává jako přihlašovací údaj typu bearer; uvedené názvy proměnných jsou místním nastavením příkazu, nikoli samostatnými parametry Cloudflare.

Od nalezeného klíče k dotazu

Po introspekci zkontrolujte pole attributes v popisu příslušné datové sady a vyberte klíč, který je skutečně uvedený. Cloudflare ukazuje příklad přesného přístupu ke klíči ve sloupci JSON: attributes['http.method']. Ve filtru použijte zjištěný název, nikoli odhad podle názvu události.

Praktický postup vypadá takto:

1. Pro požadovanou datovou sadu zavolejte introspekci s parametrem include_attributes=true.
2. Uložte klíče a typy z vráceného pole attributes spolu s datem kontroly.
3. Sestavte dotaz s přesným názvem klíče, například attributes['http.method'].
4. Ověřte dotaz na datech svého účtu a zjišťování zopakujte, pokud se změní schéma nebo charakter příchozích událostí.

Datum kontroly je užitečné pro reprodukovatelnost: Cloudflare odvozuje atributy ze sedmidenního okna, takže seznam nalezených klíčů odráží nedávná data, nikoli neměnné schéma. Pokud se požadovaný klíč v tomto období nevyskytl, jeho absence ve výsledku sama o sobě neznamená, že je obecně nedostupný.

Jak přejít ze starých názvů

Ve stávajícím kódu nahraďte parametr dotazu include_custom_attributes parametrem include_attributes a při zpracování odpovědi čtěte pole attributes místo custom_attributes. Cloudflare uvádí, že staré názvy nadále fungují, takže migraci lze provést nezávisle na případném naléhavém obnovení integrace.

Pro bezpečný přechod zkontrolujte obě části rozhraní: odesílaný parametr dotazu i cestu k poli v odpovědi. Poté spusťte dotaz nad stejnou datovou sadou a porovnejte seznam klíčů. Tento test odhalí běžnou chybu při migraci, kdy dotaz už používá nový název parametru, ale kód stále očekává staré pole odpovědi.

Co to znamená pro analytické datové pipeline

include_attributes=true zpřístupňuje dynamická pole JSON prostřednictvím oficiálního mechanismu introspekce a vývojářům poskytuje typy spolu s názvy klíčů. Nové dotazy a parsery převeďte na include_attributes a pole odpovědi attributes, ukládejte datum zjištění a filtry sestavujte podle skutečně nalezených klíčů.