跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Transformers

最后更新 查看 MarkdownAgent 设置

Transformers 允许你在 Logpush 将每批记录投递到目标之前对其运行 SQL 查询。你可以用它们过滤不想存储的记录、将字段重塑为下游 schema、脱敏敏感值、计算新字段或添加静态元数据。

你将逻辑写成一条 SQL 查询,将其附加到 Logpush 作业,然后由 Cloudflare 在每批数据上运行。FROM 子句指定 Logpush 数据集(例如 http_requests 或 audit_logs_v2),字段名来自该数据集的 schema。

Transformers 适用于受支持 Logpush 数据集的 Free、Pro、Business 和 Enterprise 计划。每个 Cloudflare 账户每月包含 1 GB 转换输入。额外输入按每 GB $0.04 计费。更多信息请参阅 Logpush 定价。

主要功能

  • 基于 SQL 的转换 - 每个 Logpush 作业一条单语句 SQL 查询。
  • 按记录执行 - 在 Cloudflare 投递批次之前,对每条 NDJSON 记录运行。
  • 高级筛选与重塑 - 删除、重命名、脱敏、计算或标记字段。
  • 无需重新部署即可附加和分离 - 从 Cloudflare 仪表板或 API 管理 transformers。
  • 版本历史 - 每次保存都会创建新版本;旧版本仍可查看。

开始之前,你需要:

  • 使用 ndjson 输出格式的 Logpush 作业。Transformers 仅适用于 NDJSON 作业,并同时支持账户作用域和 zone 作用域的数据集。
  • 如果使用 API,需要具有该账户 Logs Write 权限的 API 令牌。
  • 熟悉计划转换的记录所属 数据集。你的 SQL 会直接引用其字段名。

访问 Transformers

你可以通过 Cloudflare 仪表板或 API 创建、预览、附加和管理 transformers。

现有 Logpush 筛选器

每个 Logpush 作业可以有 transformer 或 筛选器,但不能同时拥有两者。当你在 Cloudflare 仪表板中将 transformer 附加到已有筛选器的作业时,Transformer Studio 会将现有筛选器转换为等效的 SQL 谓词。

将谓词复制到 transformer 的 WHERE 子句中以保留筛选行为。确认附加后,Transformer Studio 会移除作业筛选器并附加 transformer。

API 不会将 Logpush 筛选器转换为 SQL。要通过 API 迁移带筛选器的作业,请将筛选器转换为等效 SQL 谓词并添加到 transformer 的 WHERE 子句。然后在同一 Logpush 作业更新请求中清空 filter 并设置 transformer_id:

{
	"filter": "",
	"transformer_id": 42
}

如果设置 transformer_id 而未清空现有筛选器,API 会返回 400 响应。

Transformer Studio(UI)

Transformer Studio 是包含 SQL 编辑器的工作区,用于编写、预览和管理 Transformers。可从 Cloudflare 仪表板的 Logpush 页面打开。

前往 Logpush ↗

在 Studio 中你可以:

  • 通过对 Logpush 数据集编写 SQL 查询来创建新 transformer。
  • 在保存前,针对目标数据集的预置示例记录预览 transformer。
  • 将 transformer 附加到账户或 zone 上任何符合条件的 Logpush 作业。只有与 transformer 数据集匹配的 NDJSON 作业会显示为可附加目标。不会显示 CSV 作业。
  • 从作业中分离 transformer。
  • 每次编辑并保存 SQL 时保存新版本。旧版本仍可查看。
  • 重命名 transformer 或更新其描述。
  • 删除 transformer。只要仍有 Logpush 作业引用它,就不能删除。

API

所有 transformer 操作都可通过 Cloudflare API 使用。要完成身份验证,请使用具有 Logs Write 权限的 API 令牌。

操作 方法 端点
列出 transformers GET accounts/:account_id/logpush/transformers
创建 transformer POST accounts/:account_id/logpush/transformers
预览 transformer POST accounts/:account_id/logpush/transformers/preview
获取 transformer GET accounts/:account_id/logpush/transformers/:id
下载 SQL GET accounts/:account_id/logpush/transformers/:id/content
列出版本 GET accounts/:account_id/logpush/transformers/:id/versions
更新 transformer PUT accounts/:account_id/logpush/transformers/:id
删除 transformer DELETE accounts/:account_id/logpush/transformers/:id

以下请求创建一个 transformer,从 zone 作用域的 dns_logs 数据集中选择三个字段:

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Create transformerbash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/logpush/transformers" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "dns-query-fields",
		"description": "Selects key fields from DNS query logs.",
		"code": "SELECT QueryName, QueryType, ResponseCode FROM dns_logs"
	}'

要从作业附加或分离 transformer,请在 Logpush 作业上设置 transformer_id。作业端点请参阅 Logpush 作业设置。

SQL transformer 约定

transformer 是一条 SQL 查询。Logpush 数据集是源表;查询输出成为投递记录。

SELECT ClientIP, RayID, EdgeResponseStatus
FROM http_requests
WHERE EdgeResponseStatus >= 400

FROM 表名必须与 transformer 所附加 Logpush 作业的数据集匹配。如果不匹配,附加会失败。

不匹配 WHERE 子句的记录会从输出中丢弃。

支持的 SQL

Transformers 使用与 Basin Pipelines 相同的 SQL 方言。支持以下操作:

  • 投影 - SELECT 特定字段,使用 AS 重命名,使用表达式计算新字段。
  • 筛选 - 带有标准比较、布尔和空值检查运算符的 WHERE 子句。
  • CTE - WITH ... AS (...) 公用表表达式。
  • UNNEST - 将数组或列表字段展开为行。
  • JSON 访问 - -> 运算符返回 JSON 对象;->> 返回字符串。例如,RequestHeaders ->> 'Host'。
  • 嵌套输出 - named_struct('key', value, ...) 构建嵌套 JSON 对象。
  • 数组输出 - [value1, value2] 构建 JSON 数组。
  • 标量函数 - 标准 SQL 函数,包括 UPPER、LOWER、COALESCE、CAST、extract 和 to_timestamp。

不支持

  • Joins
  • 子查询
  • 聚合(GROUP BY、HAVING、COUNT、SUM)
  • 窗口函数
  • ORDER BY
  • 多条语句 - 每个 transformer 一条查询

验证

每条 SQL 查询在保存前都会对照目标数据集的 schema 进行验证。未知字段、错误类型、无效语法、未知数据集以及不支持的操作会在上传时被拒绝。

在仪表板中,验证错误会以内联方式显示在编辑器中,并带有行号和列号。通过 API 时,它们会返回在响应的 errors 数组中。

限制

限制 值
SQL 查询大小 250 KB
Transformer 名称长度 255 bytes
Transformer 描述长度 4,096 bytes
查询对文件系统的访问 无
查询对网络的访问 无
批次分块大小 1,000 行

示例

以下示例在单条查询中应用 主要功能 中的各项能力。每条查询都会保留一部分记录、重塑剩余记录,并丢弃下游管道不需要的字段。

筛选并重塑审计日志记录

此 transformer 仅保留审计跟踪中的 update 操作,并重塑剩余记录以便下游投递。具体而言,它会:

  • 排除所有 ActionType 不是 update 的记录。
  • 将 ActionTimestamp 从 RFC3339 转换为 Unix epoch 整数,并重命名为 unix_ts。
  • 将 ActionType 转为大写并重命名为 action_type。
  • 添加值为 Cloudflare 的硬编码 provider 字段。
  • 将 ActorType、ActorEmail 和 ActorIPAddress 分组到嵌套的 actor 对象中。
  • 根据 ResourceType = 'zone' 派生布尔标志 is_zone。
  • 从 ResourceType 和 ResourceID 构建 resource_meta 数组。
  • 通过在 SELECT 中省略来丢弃 ActorID、AccountID 和 ActorContext。

来自 audit_logs_v2 数据集的输入记录:

{
	"ActionType": "update",
	"ActorEmail": "[email protected]",
	"ActorID": "a1b2c3d4",
	"ActorIPAddress": "203.0.113.42",
	"ActorType": "user",
	"ActionTimestamp": "2026-05-21T15:00:00Z",
	"AccountID": "90796717",
	"ResourceID": "r1s2t3u4",
	"ResourceType": "zone",
	"ActorContext": "dashboard"
}

Transformer:

SELECT
  extract(epoch FROM to_timestamp(ActionTimestamp)) AS unix_ts,
  UPPER(ActionType) AS action_type,
  'Cloudflare' AS provider,
  named_struct(
    'type', ActorType,
    'email', ActorEmail,
    'ip', ActorIPAddress
  ) AS actor,
  ResourceType = 'zone' AS is_zone,
  [ResourceType, ResourceID] AS resource_meta
FROM audit_logs_v2
WHERE ActionType = 'update'

投递记录:

{
	"action_type": "UPDATE",
	"actor": {
		"email": "[email protected]",
		"ip": "203.0.113.42",
		"type": "user"
	},
	"is_zone": true,
	"provider": "Cloudflare",
	"resource_meta": ["zone", "r1s2t3u4"],
	"unix_ts": 1779375600
}

筛选并重塑 HTTP 请求记录

此 transformer 保留所有 HTTP 流量,但排除 健康检查、指标抓取器和面向内部的主机名。这是希望保留完整日志流、同时去掉可预期噪声的常见模式。具体而言,它会:

  • 排除发往 internal.example.com 和 health.example.com 的所有请求。
  • 排除路径以 /healthz 或 /metrics 开头的所有请求。
  • 将 EdgeStartTimestamp 从 RFC3339 转换为 Unix epoch 整数,并重命名为 unix_ts。
  • 将 ClientRequestMethod 转为大写并重命名为 method。
  • 添加值为 Cloudflare 的硬编码 provider 字段。
  • 将 ClientRequestHost、ClientRequestPath 和 ClientRequestMethod 分组到嵌套的 request 对象中。
  • 根据 EdgeResponseStatus >= 500 派生布尔标志 is_server_error。
  • 从 ClientRequestHost 和 ClientRequestPath 构建 request_meta 数组。
  • 通过在 SELECT 中省略来丢弃 ClientIP、ClientRequestUserAgent、RayID、OriginResponseTime 和 WAFAction。

来自 http_requests 数据集的输入记录:

{
	"ClientIP": "203.0.113.42",
	"ClientRequestHost": "example.com",
	"ClientRequestMethod": "POST",
	"ClientRequestPath": "/api/checkout",
	"ClientRequestUserAgent": "curl/7.85.0",
	"EdgeResponseStatus": 502,
	"EdgeStartTimestamp": "2026-05-21T15:00:00Z",
	"RayID": "8e2a1c60ef9e1c9a",
	"OriginResponseTime": 3200000000,
	"WAFAction": "unknown"
}

此示例假设 EdgeStartTimestamp 以 RFC3339 字符串形式投递。如果你的作业以 Unix 纳秒投递时间戳,请去掉 to_timestamp() 包装,改为除以 1e9。

Transformer:

SELECT
  extract(epoch FROM to_timestamp(EdgeStartTimestamp)) AS unix_ts,
  UPPER(ClientRequestMethod) AS method,
  'Cloudflare' AS provider,
  named_struct(
    'host', ClientRequestHost,
    'path', ClientRequestPath,
    'method', ClientRequestMethod
  ) AS request,
  EdgeResponseStatus >= 500 AS is_server_error,
  [ClientRequestHost, ClientRequestPath] AS request_meta
FROM http_requests
WHERE ClientRequestHost NOT IN ('internal.example.com', 'health.example.com')
  AND ClientRequestPath NOT LIKE '/healthz%'
  AND ClientRequestPath NOT LIKE '/metrics%'

投递记录:

{
	"is_server_error": true,
	"method": "POST",
	"provider": "Cloudflare",
	"request": {
		"host": "example.com",
		"method": "POST",
		"path": "/api/checkout"
	},
	"request_meta": ["example.com", "/api/checkout"],
	"unix_ts": 1779375600
}

错误与故障排除

API 错误

HTTP 消息 原因
403 transformer feature is not available for this account 你的账户无权使用 Transformers。
400 missing required field: name 在请求正文中添加 name 字段。
400 missing required field: code 添加包含 SQL 查询的非空 code 字段。
400 Schema validation error (unknown column, invalid syntax) SQL 引用了不存在的字段、使用了不支持的语法,或存在类型不匹配。请修复查询后重试。
413 (request entity too large) SQL 查询超过 250 KB。请缩短查询。
400 transformer N not found for this account transformer ID 不存在,或属于其他账户。
400 transformer N dataset "X" does not match job dataset "Y" transformer 的 FROM 表与作业数据集不匹配。
400 a job cannot have both a filter and a transformer configured; use one or the other 在设置 transformer_id 的同一请求中清空作业的 filter。

运行时失败

如果 transformer 在处理某批次时失败,该批次会失败:不会为其投递任何内容,错误会记录在 Logpush 作业上,然后 Logpush 按正常计划重试该批次。没有自动回退到原始日志。

如果失败持续发生,受影响批次中的记录最终会被丢弃且无法恢复。

最近一次错误会出现在作业的 last_error 字段中。常见原因:

  • 输出超过大小限制。 降低每条记录的输出,或使用 WHERE 丢弃更多记录。
  • 发生了 Cloudflare 内部错误。 请携带作业 ID 和时间戳联系 Cloudflare 支持。

要调试,请在 Transformer Studio 中打开 transformer,并使用 Run 按钮针对示例记录进行预览。验证和执行逻辑相同,因此生产中可见的问题通常也能在预览中复现。

相关资源

这篇文档对您有帮助吗?