Cloudflare обновила SQL API introspection: как обнаруживать поля JSON без догадок

Если схема аналитического набора данных содержит JSON-колонку attributes, но её ключи зависят от данных аккаунта, Cloudflare теперь позволяет обнаружить их через introspection. Обновление от 27 октября 2026 года добавило параметр include_attributes=true: ответ перечисляет ключи и типы, найденные в данных аккаунта за предшествующие семь дней.

Для разработчиков это решает конкретную задачу: перед составлением фильтра можно проверить, какие поля реально встречаются в выбранном наборе. Старые имена include_custom_attributes и custom_attributes пока работают, однако Cloudflare пометила их как устаревшие. Новые интеграции стоит строить на обновлённой SQL API introspection.

Что именно возвращает introspection

Некоторые наборы Cloudflare Analytics хранят дополнительные пары ключ—значение в колонке attributes. Introspection с новым параметром определяет ключи и их типы на основе данных за семь дней и возвращает сведения в поле attributes объекта набора данных. Это схема, выведенная из недавних записей аккаунта, которая помогает подготовить SQL-запрос.

В официальном примере Cloudflare использует маршрут /client/v4/analytics/sql/introspection, передаёт идентификатор аккаунта и имя набора events.httpRequests, а также включает обнаружение атрибутов:

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"

Перед запуском задайте переменные CLOUDFLARE_API_TOKEN и CLOUDFLARE_ACCOUNT_TAG в окружении. Токен передаётся как bearer-учётные данные; приведённые в примере имена переменных — локальные настройки команды, а не отдельные параметры Cloudflare.

От найденного ключа к запросу

После introspection проверьте поле attributes в описании нужного набора и выберите фактически перечисленный ключ. Cloudflare показывает пример точного обращения к ключу JSON-колонки: attributes['http.method']. Используйте в фильтре обнаруженное имя, а не предполагаемое по названию события.

Практический порядок работы выглядит так:

1. Запросите introspection для нужного набора данных с include_attributes=true.
2. Сохраните ключи и типы из возвращённого поля attributes вместе с датой проверки.
3. Соберите запрос, используя точное имя ключа, например attributes['http.method'].
4. Проверьте запрос на данных своего аккаунта и повторите обнаружение, когда схема или характер входящих событий меняются.

Дата проверки полезна для воспроизводимости: Cloudflare выводит атрибуты из семидневного окна, поэтому набор обнаруженных ключей отражает недавние данные, а не неизменную схему. Если нужный ключ не встречался в этом окне, его отсутствие в результате само по себе не позволяет считать его универсально недоступным.

Как перейти со старых имён

В существующем коде замените параметр запроса include_custom_attributes на include_attributes, а обработку поля ответа custom_attributes — на чтение attributes. Cloudflare сообщает, что прежние имена продолжают работать, поэтому миграцию можно провести отдельно от срочного восстановления интеграции.

Для безопасного перехода проверьте оба участка контракта: отправляемый query-параметр и путь к полю в ответе. Затем запустите запрос на одном и том же наборе и сравните список ключей. Такой тест обнаружит типичную ошибку миграции, когда запрос уже использует новое имя параметра, а код всё ещё ожидает старое поле ответа.

Итог для аналитических пайплайнов

include_attributes=true делает динамические JSON-поля обнаруживаемыми через официальный механизм introspection и даёт разработчикам типы вместе с именами ключей. Переведите новые запросы и парсеры на include_attributes и ответное поле attributes, храните дату обнаружения и формируйте фильтры по реально найденным ключам.