Michael Johnson如果分析数据集的架构包含 JSON 列 attributes，但其中的键取决于账户数据，Cloudflare 现在支持通过内省发现这些键。2026 年 10 月 27 日发布的更新新增了 include_attributes=true 参数：响应会列出过去七天账户数据中发现的键及其类型。
对开发者而言，这解决了一个具体问题：构建筛选条件前，可以先检查所选数据集中实际出现了哪些字段。旧名称 include_custom_attributes 和 custom_attributes 目前仍可使用，但 Cloudflare 已将它们标记为弃用。建议新集成使用更新后的 SQL API 内省功能。
内省具体会返回什么
部分 Cloudflare Analytics 数据集会在 attributes 列中存储额外的键值对。使用新参数进行内省，会根据过去七天的数据识别键及其类型，并将信息返回在数据集对象的 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 的独立参数。
从发现的键到查询
完成内省后，检查所需数据集描述中的 attributes 字段，并选择实际列出的键。Cloudflare 展示了精确访问 JSON 列键的示例：attributes['http.method']。筛选时应使用发现的名称，而不是根据事件名称推测。
实际操作流程如下：
- 为所需数据集发起带有
include_attributes=true的内省请求。 - 保存返回的
attributes字段中的键和类型，并记录检查日期。 - 使用准确的键名构建查询，例如
attributes['http.method']。 - 在自己的账户数据上验证查询；架构或传入事件特征发生变化时，重新执行发现。
记录检查日期有助于复现结果：Cloudflare 根据七天窗口推导属性，因此发现的键集合反映的是近期数据，而非固定不变的架构。如果所需键在该时间窗口内没有出现，仅凭它未出现在结果中，并不能断定它始终不可用。
如何从旧名称迁移
在现有代码中，将查询参数 include_custom_attributes 替换为 include_attributes，并将响应字段 custom_attributes 的处理改为读取 attributes。Cloudflare 表示旧名称仍可使用，因此迁移可以分步完成，无需为了恢复集成而立即匆忙处理。
为确保迁移安全，请检查接口约定的两个部分：发送的查询参数，以及响应中的字段路径。随后针对同一数据集运行请求并比较键列表。这样可以发现常见的迁移错误：请求已使用新参数名称，但代码仍在等待旧的响应字段。
对分析数据管道的意义
include_attributes=true 让动态 JSON 字段能够通过官方内省机制被发现，并让开发者同时获取键名和类型。请将新查询和解析器改为使用 include_attributes 参数及响应字段 attributes，记录发现日期，并依据实际发现的键构建筛选条件。
