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

自定义字段

最后更新 查看 MarkdownAgent 设置

HTTP 请求数据集默认包含大多数标准日志信息。不过,如果您需要捕获额外的请求或响应标头或 Cookie,可以使用自定义字段,使日志满足您的特定需求

自定义字段按 zone 配置,适用于处理该 zone 的所有 HTTP requests Logpush 作业,包括账户范围的作业。作业必须包含请求标头、响应标头或 Cookie 字段。你可以记录这些字段的原始值或转换后的值。

账户范围的作业会遵循每个 zone 的自定义字段配置。你无法在账户中为所有 zone 统一配置一次自定义字段。

此默认行为可以更改。您可以根据需要将请求或响应标头配置为以原始值或转换后的值记录——但不能对同一标头同时使用两种方式。

自定义字段可通过 API 或 Cloudflare 仪表板启用。

通过 API 启用自定义字段

使用 Rulesets API 创建用于配置自定义字段的规则。有关 phase、规则集和规则等概念以及可用 API 操作的更多信息,请参阅 Ruleset Engine 文档。

要配置自定义字段:

  1. 创建一条规则以配置自定义字段列表。
  2. 在您的 Logpush 作业中包含 Cookies、RequestHeaders 和/或 ResponseHeaders 字段。

1. 创建规则以配置自定义字段列表

在 zone 级别的 http_log_custom_fields phase 中创建一条配置自定义字段列表的规则。将规则操作设为 log_custom_field,将规则表达式设为 true。

必须在配置自定义字段列表的规则中包含的 action_parameters 对象应具有以下结构:

"action_parameters": {
//select raw (default) or transformed request header
  "request_fields": [
    { "name": "<http_request_header_raw>" }
  ],
  "transformed_request_fields": [
    { "name": "<http_request_header_transformed>" }
  ],
//select raw or transformed (default) response header
  "response_fields": [
    { "name": "<http_response_header_transformed>" }
  ],
  "raw_response_fields": [
    { "name": "<http_response_header_raw>" }
  ],
  "cookie_fields": [
    { "name": "<cookie_name>" }
  ]
}

请确保您的规则定义符合以下要求:

  • 您必须在 action_parameters 对象中至少包含以下数组之一:request_fields、transformed_request_fields、response_fields、raw_response_fields 和 cookie_fields。
  • HTTP 请求和响应标头名称必须以小写输入。
  • Cookie 名称区分大小写——您必须以与 HTTP 请求中相同的大小写输入 Cookie 名称。
  • 您必须将规则表达式设为 true。
  • 对于请求或响应标头,您只能记录原始值或转换后的值,不能对同一标头同时使用两者。

按以下步骤创建规则:

  1. 使用列出 zone 规则集操作,检查 zone 级别的 http_log_custom_fields phase 是否已有入口点规则集(每个 phase 只能有一个入口点规则集):

    List zone rulesetsbash
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
    	--request GET \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

    如果存在 http_log_custom_fields phase 的入口点规则集(即 "kind": "zone" 且 "phase": "http_log_custom_fields" 的规则集),请记下规则集 ID。

  2. (可选)如果响应中未包含 "kind": "zone" 且 "phase": "http_log_custom_fields" 的规则集,请使用创建 zone 规则集操作创建该 phase 的入口点规则集:

    Create a zone rulesetbash
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
    	--request POST \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    	--json '{
    		"name": "Zone-level phase entry point",
    		"kind": "zone",
    		"description": "This ruleset configures custom log fields.",
    		"phase": "http_log_custom_fields"
    	}'

    记下响应中包含的规则集 ID。

  3. 使用更新 zone 规则集操作定义您找到(或在上一步中创建)的入口点规则集的规则,添加一条包含自定义字段配置的规则。请求中包含的规则将替换规则集中的所有规则。

    以下示例配置自定义字段,包含您希望在 Logpush 日志中包含的 HTTP 请求标头、HTTP 响应标头和 Cookie 的名称:

    Update a zone rulesetbash
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
    	--request PUT \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    	--json '{
    		"rules": [
    				{
    						"action": "log_custom_field",
    						"expression": "true",
    						"description": "Set Logpush custom fields for HTTP requests",
    						"action_parameters": {
    								"request_fields": [
    										{
    												"name": "content-type"
    										},
    										{
    												"name": "x-forwarded-for"
    										}
    								],
    								"transformed_request_fields": [
    										{
    												"name": "host"
    										}
    								],
    								"response_fields": [
    										{
    												"name": "server"
    										},
    										{
    												"name": "content-type"
    										}
    								],
    								"raw_response_fields": [
    										{
    												"name": "allow"
    										}
    								],
    								"cookie_fields": [
    										{
    												"name": "__ga"
    										},
    										{
    												"name": "accountNumber"
    										},
    										{
    												"name": "__cfruid"
    										}
    								]
    						}
    				}
    		]
    	}'
    {
        "result": {
            "id": "<RULESET_ID>",
            "name": "Zone-level phase entry point",
            "description": "This ruleset configures custom log fields.",
            "kind": "zone",
            "version": "2",
            "rules": [
                {
                    "id": "<RULE_ID_1>",
                    "version": "1",
                    "action": "log_custom_field",
                    "action_parameters": {
                        "request_fields": [
                            { "name": "content-type" },
                            { "name": "x-forwarded-for" }
                        ],
                        "transformed_request_fields": [{ "name": "host" }],
                        "response_fields": [
                            { "name": "server" },
                            { "name": "content-type" }
                        ],
                        "raw_response_fields": [{ "name": "allow" }],
                        "cookie_fields": [
                            { "name": "__ga" },
                            { "name": "accountNumber" },
                            { "name": "__cfruid" }
                        ]
                    },
                    "expression": "true",
                    "description": "Set Logpush custom fields for HTTP requests",
                    "last_updated": "2021-11-21T11:02:08.769537Z",
                    "ref": "<RULE_REF_1>",
                    "enabled": true
                }
            ],
            "last_updated": "2021-11-21T11:02:08.769537Z",
            "phase": "http_log_custom_fields"
        },
        "success": true,
        "errors": [],
        "messages": []
    }

记录重复的响应标头值

某些从源站发送的标头(例如 set-cookie)可能有多个您想要捕获的值。您可以使用 Rulesets API 指定哪些标头应记录其所有值。

Update a zone rulesetbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"action": "log_custom_field",
						"expression": "true",
						"description": "Set Logpush custom fields for HTTP requests",
						"action_parameters": {
								"response_fields": [
										{
												"name": "set-cookie",
												"preserve_duplicates": true
										}
								]
						}
				}
		]
	}'

请注意,preserve_duplicates 同时适用于 response_fields 和 raw_response_fields。如果没有影响该标头的转换规则,在 response_fields 或 raw_response_fields 中包含 preserve_duplicates 应能达到相同结果。

在此示例中,将记录 set-cookie 标头的所有值。它们将作为字符串值数组出现在 ResponseFields 下,例如:

{
  // ...
  "ResponseFields": {
    "set-cookie": ["name1=val1", "name2=val2", ...]
  }
}

您可以使用 Worker 或 Logpush 目标处的自定义逻辑来提取这些值。

2. 在 Logpush 作业中包含自定义字段

接下来,在创建或更新作业时,根据您的自定义字段配置,在 output_options 作业参数的字段列表中包含 Cookies、RequestHeaders、ResponseHeaders 和/或 ResponseFields。日志将包含配置的自定义字段及其在请求/响应中的值。

例如,请考虑以下创建包含自定义字段的作业的请求:

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Create Logpush jobbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "<DOMAIN_NAME>",
		"destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
		"dataset": "http_requests",
		"output_options": {
				"field_names": [
						"RayID",
						"EdgeStartTimestamp",
						"Cookies",
						"RequestHeaders",
						"ResponseHeaders"
				],
				"timestamp_format": "rfc3339"
		},
		"ownership_challenge": "<OWNERSHIP_CHALLENGE_TOKEN>"
	}'

通过仪表板启用自定义字段

  1. 在 Cloudflare 仪表板中,选择你的账户和 zone。然后前往 Observability > Export > Logpush。

    前往 Logpush configuration(Logpush 配置) ↗
  2. 选择 Configuration 选项卡。

  3. 在 Custom log fields(自定义日志字段) 部分,选择 Edit Custom Fields(编辑自定义字段)。

  4. 选择 Set new Custom Field(设置新的自定义字段)。

  5. 在 Field Type 下拉菜单中,选择 Request Header、Response Header 或 Cookies,然后输入 Field Name。

  6. 完成后,选择 Save(保存)。

用例:记录 mTLS 证书标头

要在 Logpush 中记录 mTLS 证书详情(例如 cf-cert-subject-dn 或 cf-cert-issuer-dn),您需要:

  1. 启用 Add TLS client auth headers 托管转换,以注入证书标头。
  2. 使用 transformed_request_fields(而非 request_fields)配置 Logpush 自定义字段,以捕获这些由 Cloudflare 注入的标头。
  3. 确保您的 Logpush 作业包含 RequestHeaders 字段。

mTLS 标头是在收到客户端请求后由 Cloudflare 注入的,因此必须使用 transformed_request_fields 而非 request_fields 来捕获。

有关配置客户端证书的更多信息,请参阅 mTLS 身份验证。

限制

  • 自定义字段允许每种字段类型 100 个标头——此限制分别适用于 request_fields、transformed_request_fields、response_fields、raw_response_fields 和 cookie_fields。
  • 请求标头 Range 目前不受自定义字段支持。
  • 请求和响应标头的转换值和原始值仅可通过 API 使用,无法通过 UI 设置。

这篇文档对您有帮助吗?