Michael JohnsonOm schemat för en analysdatamängd innehåller JSON-kolumnen attributes, men dess nycklar beror på kontodata, kan Cloudflare nu hjälpa dig att upptäcka dem genom introspektion. Uppdateringen den 27 oktober 2026 lade till parametern include_attributes=true: svaret listar nycklar och typer som hittats i kontodata under de föregående sju dagarna.
För utvecklare löser detta ett konkret problem: innan du skapar ett filter kan du kontrollera vilka fält som faktiskt förekommer i den valda datamängden. De äldre namnen include_custom_attributes och custom_attributes fungerar fortfarande, men Cloudflare har markerat dem som föråldrade. Nya integrationer bör bygga på den uppdaterade introspektionen för SQL API.
Vad introspektionen returnerar
Vissa datamängder i Cloudflare Analytics lagrar ytterligare nyckel–värde-par i kolumnen attributes. Med den nya parametern identifierar introspektionen nycklar och deras typer utifrån data från sju dagar och returnerar informationen i fältet attributes för datamängdsobjektet. Det är ett schema som härletts från kontots senaste poster och som kan hjälpa dig att förbereda en SQL-fråga.
I Cloudflares officiella exempel används rutten /client/v4/analytics/sql/introspection, tillsammans med ett konto-ID och datamängdsnamnet events.httpRequests, och attributupptäckt aktiveras:
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"Innan du kör kommandot anger du variablerna CLOUDFLARE_API_TOKEN och CLOUDFLARE_ACCOUNT_TAG i miljön. Token skickas som autentiseringsuppgift av typen bearer; variabelnamnen i exemplet är lokala inställningar för kommandot, inte separata Cloudflare-parametrar.
Från upptäckt nyckel till fråga
Efter introspektionen kontrollerar du fältet attributes i beskrivningen av den aktuella datamängden och väljer en nyckel som faktiskt listas där. Cloudflare visar ett exempel på exakt åtkomst till en nyckel i JSON-kolumnen: attributes['http.method']. Använd det upptäckta namnet i filtret i stället för att gissa utifrån händelsens namn.
Arbetsgången i praktiken ser ut så här:
- Begär introspektion för den aktuella datamängden med
include_attributes=true. - Spara nycklarna och typerna från det returnerade fältet
attributestillsammans med datumet då kontrollen gjordes. - Skapa frågan med det exakta nyckelnamnet, till exempel
attributes['http.method']. - Testa frågan med data från ditt konto och upprepa upptäckten när schemat eller de inkommande händelserna förändras.
Kontrolldatumet är användbart för reproducerbarhet: Cloudflare härleder attributen från ett sjudagarsfönster, så de upptäckta nycklarna speglar nyliga data, inte ett oföränderligt schema. Om en nyckel inte förekommit under den perioden innebär frånvaron i resultatet inte i sig att den aldrig är tillgänglig.
Så byter du från de äldre namnen
I befintlig kod ersätter du frågeparametern include_custom_attributes med include_attributes och ändrar hanteringen av svarsfältet från custom_attributes till attributes. Cloudflare uppger att de tidigare namnen fortsätter att fungera, så migreringen kan genomföras separat från eventuell akut felsökning av integrationen.
Kontrollera båda delarna av kontraktet för en säker övergång: frågeparametern som skickas och sökvägen till fältet i svaret. Kör sedan frågan mot samma datamängd och jämför listan över nycklar. Testet fångar ett vanligt migreringsfel: frågan använder redan det nya parameternamnet, medan koden fortfarande förväntar sig det gamla svarsfältet.
Slutsatser för analysflöden
include_attributes=true gör dynamiska JSON-fält upptäckbara via den officiella introspektionsmekanismen och ger utvecklare typer tillsammans med nyckelnamn. Uppdatera nya frågor och parsrar så att de använder include_attributes och svarsfältet attributes, spara datumet för upptäckten och skapa filter utifrån nycklar som faktiskt hittats.
