Michael JohnsonЯкщо схема аналітичного набору даних містить JSON-колонку attributes, але її ключі залежать від даних облікового запису, Cloudflare тепер дає змогу виявити їх через introspection. Оновлення від 27 жовтня 2026 року додало параметр include_attributes=true: відповідь перелічує ключі та типи, знайдені в даних облікового запису за попередні сім днів.
Для розробників це розв’язує конкретне завдання: перед створенням фільтра можна перевірити, які поля справді трапляються у вибраному наборі. Старі назви include_custom_attributes і custom_attributes поки працюють, однак Cloudflare позначила їх як застарілі. Нові інтеграції варто будувати на оновленому introspection SQL API.
Що саме повертає 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']. Використовуйте у фільтрі знайдену назву, а не ту, яку припускаєте за назвою події.
Практичний порядок роботи такий:
- Запитайте introspection для потрібного набору даних із параметром
include_attributes=true. - Збережіть ключі й типи з поверненого поля
attributesразом із датою перевірки. - Складіть запит, використовуючи точну назву ключа, наприклад
attributes['http.method']. - Перевірте запит на даних свого облікового запису й повторіть виявлення, коли зміняться схема або характер вхідних подій.
Дата перевірки корисна для відтворюваності: Cloudflare виводить атрибути із семиденного вікна, тому набір виявлених ключів відображає недавні дані, а не незмінну схему. Якщо потрібний ключ не траплявся в цьому вікні, його відсутність у результаті сама по собі не означає, що він недоступний завжди.
Як перейти зі старих назв
У наявному коді замініть параметр запиту include_custom_attributes на include_attributes, а обробку поля відповіді custom_attributes — на читання attributes. Cloudflare повідомляє, що попередні назви продовжують працювати, тож міграцію можна виконати окремо від термінового відновлення інтеграції.
Для безпечного переходу перевірте обидві частини контракту: параметр запиту, що надсилається, і шлях до поля у відповіді. Потім виконайте запит до того самого набору й порівняйте списки ключів. Такий тест виявить типову помилку міграції, коли запит уже використовує нову назву параметра, а код усе ще очікує старе поле відповіді.
Висновок для аналітичних конвеєрів
include_attributes=true робить динамічні поля JSON доступними для виявлення через офіційний механізм introspection і надає розробникам типи разом із назвами ключів. Переведіть нові запити й парсери на include_attributes і поле відповіді attributes, зберігайте дату виявлення та створюйте фільтри на основі фактично знайдених ключів.
