Cloudflare aktualizuje introspekcję SQL API: wykrywanie pól JSON bez zgadywania

Jeśli schemat analitycznego zbioru danych zawiera kolumnę JSON attributes, ale jej klucze zależą od danych konta, Cloudflare umożliwia teraz ich wykrywanie za pomocą introspekcji. Aktualizacja z 27 października 2026 roku dodała parametr include_attributes=true: odpowiedź wylicza klucze i typy znalezione w danych konta z poprzednich siedmiu dni.

Dla programistów rozwiązuje to konkretny problem: przed utworzeniem filtra można sprawdzić, które pola rzeczywiście występują w wybranym zbiorze. Dotychczasowe nazwy include_custom_attributes i custom_attributes nadal działają, ale Cloudflare oznaczył je jako przestarzałe. Nowe integracje warto oprzeć na zaktualizowanej introspekcji SQL API.

Co dokładnie zwraca introspekcja

Niektóre zbiory Cloudflare Analytics przechowują dodatkowe pary klucz–wartość w kolumnie attributes. Introspekcja z nowym parametrem określa klucze i ich typy na podstawie danych z siedmiu dni, a następnie zwraca te informacje w polu attributes obiektu zbioru danych. Jest to schemat wywnioskowany z niedawnych zapisów na koncie, który pomaga przygotować zapytanie SQL.

W oficjalnym przykładzie Cloudflare używa ścieżki /client/v4/analytics/sql/introspection, przekazuje identyfikator konta i nazwę zbioru events.httpRequests, a także włącza wykrywanie atrybutów:

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"

Przed uruchomieniem ustaw w środowisku zmienne CLOUDFLARE_API_TOKEN i CLOUDFLARE_ACCOUNT_TAG. Token jest przekazywany jako poświadczenie typu bearer; podane w przykładzie nazwy zmiennych to lokalne ustawienia polecenia, a nie osobne parametry Cloudflare.

Od znalezionego klucza do zapytania

Po introspekcji sprawdź pole attributes w opisie odpowiedniego zbioru i wybierz faktycznie wymieniony klucz. Cloudflare pokazuje przykład dokładnego odwołania do klucza w kolumnie JSON: attributes['http.method']. W filtrze użyj wykrytej nazwy, a nie tej, którą można zgadywać na podstawie nazwy zdarzenia.

Praktyczny przebieg pracy wygląda następująco:

1. Wyślij zapytanie introspekcyjne dla właściwego zbioru danych z parametrem include_attributes=true.
2. Zapisz klucze i typy z otrzymanego pola attributes wraz z datą sprawdzenia.
3. Utwórz zapytanie, używając dokładnej nazwy klucza, na przykład attributes['http.method'].
4. Sprawdź zapytanie na danych swojego konta i ponów wykrywanie, gdy zmieni się schemat lub charakter przychodzących zdarzeń.

Data sprawdzenia ułatwia odtworzenie wyników: Cloudflare wyprowadza atrybuty z siedmiodniowego okna, więc wykryte klucze odzwierciedlają niedawne dane, a nie niezmienny schemat. Jeśli dany klucz nie wystąpił w tym oknie, jego brak w wyniku nie oznacza sam w sobie, że jest on zawsze niedostępny.

Jak przejść ze starych nazw

W istniejącym kodzie zamień parametr zapytania include_custom_attributes na include_attributes, a obsługę pola odpowiedzi custom_attributes — na odczyt pola attributes. Cloudflare informuje, że poprzednie nazwy nadal działają, więc migrację można przeprowadzić niezależnie od pilnego przywracania integracji.

Aby bezpiecznie przejść na nowe nazwy, sprawdź oba elementy kontraktu: wysyłany parametr zapytania oraz ścieżkę do pola w odpowiedzi. Następnie uruchom zapytanie dla tego samego zbioru i porównaj listę kluczy. Taki test wykryje typowy błąd migracji, gdy zapytanie używa już nowej nazwy parametru, a kod nadal oczekuje starego pola odpowiedzi.

Podsumowanie dla potoków analitycznych

include_attributes=true umożliwia wykrywanie dynamicznych pól JSON za pomocą oficjalnego mechanizmu introspekcji i dostarcza programistom typy wraz z nazwami kluczy. Zaktualizuj nowe zapytania i parsery, aby korzystały z include_attributes i pola odpowiedzi attributes, zapisuj datę wykrycia i twórz filtry na podstawie faktycznie znalezionych kluczy.