Michael Johnson分析データセットのスキーマにJSON列attributesがあっても、そのキーがアカウントのデータによって異なる場合、Cloudflareのイントロスペクションでキーを検出できるようになりました。2026年10月27日の更新でinclude_attributes=trueパラメーターが追加され、過去7日間のアカウントデータで見つかったキーと型がレスポンスに列挙されます。
開発者にとって、これは具体的な課題を解決します。フィルターを作成する前に、選択したデータセットに実際に存在するフィールドを確認できます。以前の名称であるinclude_custom_attributesとcustom_attributesも引き続き動作しますが、Cloudflareは非推奨としています。新しい連携では更新されたSQL APIイントロスペクションを利用してください。
イントロスペクションで返される情報
Cloudflare Analyticsの一部のデータセットでは、追加のキーと値のペアがattributes列に格納されています。新しいパラメーターを使ったイントロスペクションは、過去7日間のデータをもとにキーと型を判定し、データセットオブジェクトのattributesフィールドに情報を返します。これはアカウントの最近のレコードから導出したスキーマで、SQLクエリの準備に役立ちます。
Cloudflareの公式例では、/client/v4/analytics/sql/introspectionエンドポイントにアカウントIDとデータセット名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の個別パラメーターではありません。
検出したキーをクエリに使う
イントロスペクション後、対象データセットの説明にあるattributesフィールドを確認し、実際に列挙されたキーを選択します。CloudflareはJSON列のキーを正確に指定する例としてattributes['http.method']を示しています。イベント名から推測せず、検出された名前をフィルターに使ってください。
実務では、次の手順で進めます。
- 対象のデータセットに対し、
include_attributes=trueを指定してイントロスペクションを実行します。 - 返された
attributesフィールドのキーと型を、確認日とともに保存します。 attributes['http.method']のように、キーの正確な名前を使ってクエリを組み立てます。- アカウントのデータでクエリを検証し、スキーマや受信イベントの傾向が変わったら、再度検出します。
確認日を記録すると再現性が高まります。Cloudflareが属性を導出するのは7日間のウィンドウ内のデータであり、検出されたキーは不変のスキーマではなく最近のデータを反映するためです。必要なキーがその期間に現れなかった場合、結果にないことだけを根拠に、そのキーが常に利用できないとは判断できません。
旧名称からの移行方法
既存コードでは、クエリパラメーターinclude_custom_attributesをinclude_attributesに、レスポンスフィールドcustom_attributesの処理をattributesの読み取りに変更します。Cloudflareによると従来の名称も引き続き動作するため、連携の緊急復旧とは切り分けて移行できます。
安全に移行するには、送信するクエリパラメーターとレスポンス内のフィールドパスの両方を確認してください。その後、同じデータセットに対してクエリを実行し、キーの一覧を比較します。このテストで、新しいパラメーター名を使っているのに、コードが古いレスポンスフィールドを待ち受けているという典型的な移行ミスを検出できます。
分析パイプラインへの影響
include_attributes=trueにより、動的なJSONフィールドを公式のイントロスペクション機能で検出でき、キー名とともに型も取得できます。新しいクエリとパーサーをinclude_attributesおよびレスポンスのattributesフィールドに対応させ、検出日を記録し、実際に見つかったキーに基づいてフィルターを作成してください。
