Cloudflare päivitti SQL API:n introspection-toimintoa: löydä JSON-kentät arvailematta

Jos analytiikkatietojoukon skeema sisältää JSON-sarakkeen attributes, mutta sen avaimet riippuvat tilin datasta, Cloudflare mahdollistaa nyt niiden löytämisen introspection-toiminnon avulla. 27. lokakuuta 2026 julkaistussa päivityksessä lisättiin parametri include_attributes=true: vastaus luettelee tilin datasta edeltävien seitsemän päivän ajalta löytyneet avaimet ja tyypit.

Kehittäjille tämä ratkaisee konkreettisen ongelman: ennen suodattimen laatimista voi tarkistaa, mitä kenttiä valitussa tietojoukossa todella esiintyy. Vanhat nimet include_custom_attributes ja custom_attributes toimivat toistaiseksi, mutta Cloudflare on merkinnyt ne vanhentuviksi. Uudet integraatiot kannattaa rakentaa päivitetyn SQL API:n introspection-toiminnon varaan.

Mitä introspection palauttaa

Joihinkin Cloudflaren Analytics-tietojoukkoihin tallennetaan lisäavaimen ja arvon pareja attributes-sarakkeeseen. Uusi parametri määrittää seitsemän päivän datan perusteella käytetyt avaimet ja niiden tyypit ja palauttaa tiedot tietojoukko-olion attributes-kentässä. Kyseessä on tilin viimeaikaisista tietueista päätelty skeema, joka auttaa valmistelemaan SQL-kyselyä.

Cloudflaren virallisessa esimerkissä käytetään reittiä /client/v4/analytics/sql/introspection, annetaan tilin tunniste ja tietojoukon nimi events.httpRequests sekä otetaan attribuuttien tunnistus käyttöön:

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"

Aseta muuttujat CLOUDFLARE_API_TOKEN ja CLOUDFLARE_ACCOUNT_TAG ympäristöön ennen komennon suorittamista. Tunniste välitetään bearer-tunnistetietona; esimerkissä käytetyt muuttujien nimet ovat paikallisia komentoympäristön asetuksia, eivät erillisiä Cloudflare-parametreja.

Löydetystä avaimesta kyselyyn

Introspectionin jälkeen tarkista halutun tietojoukon kuvauksen attributes-kenttä ja valitse siinä lueteltu avain. Cloudflare näyttää esimerkin JSON-sarakkeen avaimen täsmällisestä käytöstä: attributes['http.method']. Käytä suodattimessa löydettyä nimeä sen sijaan, että päättelisit sen tapahtuman nimen perusteella.

Käytännön työjärjestys on seuraava:

1. Tee halutulle tietojoukolle introspection-kysely parametrilla include_attributes=true.
2. Tallenna palautetun attributes-kentän avaimet ja tyypit tarkistuspäivämäärän kanssa.
3. Rakenna kysely käyttäen tarkkaa avaimen nimeä, esimerkiksi attributes['http.method'].
4. Testaa kysely tilisi datalla ja toista tunnistus, kun skeema tai saapuvien tapahtumien luonne muuttuu.

Tarkistuspäivämäärä auttaa toistettavuudessa: Cloudflare päättelee attribuutit seitsemän päivän aikaikkunasta, joten löydetyt avaimet kuvaavat viimeaikaista dataa eivätkä muuttumatonta skeemaa. Jos tarvittavaa avainta ei ole esiintynyt tässä aikaikkunassa, sen puuttuminen tuloksista ei yksinään osoita, ettei avain olisi yleisesti käytettävissä.

Näin siirryt vanhoista nimistä uusiin

Korvaa olemassa olevassa koodissa kyselyparametri include_custom_attributes parametrilla include_attributes ja muuta vastauskentän käsittely lukemaan attributes kentän custom_attributes sijaan. Cloudflaren mukaan vanhat nimet toimivat edelleen, joten siirron voi tehdä erillään kiireellisistä integraation korjaustoimista.

Tarkista turvallista siirtymää varten sopimuksen molemmat osat: lähetettävä kyselyparametri ja vastauskentän polku. Suorita sitten kysely samalle tietojoukolle ja vertaa avainluetteloita. Näin löytyy tyypillinen siirtymävirhe, jossa kysely käyttää jo uutta parametrinimeä, mutta koodi odottaa edelleen vanhaa vastauskenttää.

Yhteenveto analytiikkaputkille

include_attributes=true tekee dynaamisista JSON-kentistä löydettäviä virallisen introspection-mekanismin kautta ja antaa kehittäjille avainten nimien lisäksi niiden tyypit. Päivitä uudet kyselyt ja jäsentimet käyttämään parametria include_attributes ja vastauskenttää attributes, tallenna tunnistuspäivämäärä ja muodosta suodattimet todella löydettyjen avainten perusteella.