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

通过 API 创建响应头转换规则

最后更新 查看 MarkdownAgent 设置

使用 Rulesets API 通过 API 创建响应头转换规则(Response Header Transform Rules)。常见用例请参阅 Rules 示例库。

如果使用 Terraform,请参阅 使用 Terraform 配置 Transform Rules。

基本规则设置

通过 API 创建响应头转换规则时,请确保:

  • 将规则操作(action)设为 rewrite。
  • 根据要执行的操作(设置、添加或移除标头),在 action_parameters 字段中定义标头修改参数。
  • 将规则部署到 zone 级别的 http_response_headers_transform phase。

操作步骤

通过 API 为给定 zone 创建 a response header transform rule 时,请遵循以下工作流:

  1. 使用 List zone rulesets 操作检查 zone 级别是否已有 http_response_headers_transform phase 的 ruleset。

  2. 如果 phase ruleset 不存在,使用 Create a zone ruleset 操作创建。在新 ruleset 属性中设置以下值:

    • kind:zone
    • phase:http_response_headers_transform
  3. 使用 Update a zone ruleset 操作将 a response header transform rule 添加到 ruleset 规则列表。或者,在上一步的 Create a zone ruleset 请求中包含该规则。

请确保你的 API 令牌具有执行 API 操作所需的权限。

示例请求

示例:将 HTTP 响应标头设置为静态值

以下示例使用 Update a zone ruleset 操作,将现有 phase ruleset($RULESET_ID)的规则配置为单条响应头转换规则——将 HTTP 响应头设为静态值。响应将包含你所更新的 ruleset 的完整定义。

Required API token permissions

At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
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": [
				{
						"ref": "set_resp_header_source",
						"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
						"description": "My first response header transform rule",
						"action": "rewrite",
						"action_parameters": {
								"headers": {
										"X-Source": {
												"operation": "set",
												"value": "Cloudflare"
										}
								}
						}
				}
		]
	}'
{
	"result": {
		"id": "<RULESET_ID>",
		"name": "Zone-level Response Headers Transform Ruleset",
		"description": "Zone-level ruleset that will execute Response Header Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"ref": "set_resp_header_source",
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"headers": {
						"X-Source": {
							"operation": "set",
							"value": "Cloudflare"
						}
					}
				},
				"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
				"description": "My first response header transform rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_response_headers_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

使用 Terraform 时,通过 ref 字段使规则 ID 在更新之间保持稳定。添加此字段可防止 Terraform 在发生变更时重新创建规则。更多信息请参阅 Terraform 文档中的故障排除。

示例:将 HTTP 响应标头设置为动态值

以下示例使用 Update a zone ruleset 操作,将现有 phase ruleset($RULESET_ID)的规则配置为单条响应头转换规则——将 HTTP 响应头设为动态值。响应将包含你所更新的 ruleset 的完整定义。

Required API token permissions

At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
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": [
				{
						"ref": "set_resp_header_bot_score",
						"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
						"description": "My first response header transform rule",
						"action": "rewrite",
						"action_parameters": {
								"headers": {
										"X-Bot-Score": {
												"operation": "set",
												"expression": "to_string(cf.bot_management.score)"
										}
								}
						}
				}
		]
	}'
{
	"result": {
		"id": "<RULESET_ID>",
		"name": "Zone-level Response Headers Transform Ruleset",
		"description": "Zone-level ruleset that will execute Response Header Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"ref": "set_resp_header_bot_score",
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"headers": {
						"X-Bot-Score": {
							"operation": "set",
							"expression": "to_string(cf.bot_management.score)"
						}
					}
				},
				"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
				"description": "My first response header transform rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_response_headers_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

使用 Terraform 时,通过 ref 字段使规则 ID 在更新之间保持稳定。添加此字段可防止 Terraform 在发生变更时重新创建规则。更多信息请参阅 Terraform 文档中的故障排除。

示例:添加具有静态值的 set-cookie HTTP 响应标头

以下示例使用 Update a zone ruleset 操作,将现有 phase ruleset($RULESET_ID)的规则配置为单条响应头转换规则——添加带静态值的 set-cookie HTTP 响应头。通过使用 add 操作配置规则,将保留响应中可能已存在的任何 set-cookie 标头。响应将包含你所更新的 ruleset 的完整定义。

Required API token permissions

At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
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": [
				{
						"ref": "add_resp_header_set_mycookie",
						"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
						"description": "My first response header transform rule",
						"action": "rewrite",
						"action_parameters": {
								"headers": {
										"set-cookie": {
												"operation": "add",
												"value": "mycookie=custom_value"
										}
								}
						}
				}
		]
	}'
{
	"result": {
		"id": "<RULESET_ID>",
		"name": "Zone-level Response Headers Transform Ruleset",
		"description": "Zone-level ruleset that will execute Response Header Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"ref": "add_resp_header_set_mycookie",
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"headers": {
						"set-cookie": {
							"operation": "add",
							"value": "mycookie=custom_value"
						}
					}
				},
				"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
				"description": "My first response header transform rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_response_headers_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

使用 Terraform 时,通过 ref 字段使规则 ID 在更新之间保持稳定。添加此字段可防止 Terraform 在发生变更时重新创建规则。更多信息请参阅 Terraform 文档中的故障排除。

示例:移除 HTTP 响应标头

以下示例使用 Update a zone ruleset 操作,将现有 phase ruleset($RULESET_ID)的规则设为单条响应头转换规则——移除一个 HTTP 响应头。响应将包含你所更新的 ruleset 的完整定义。

Required API token permissions

At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
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": [
				{
						"ref": "remove_resp_header_cf_connecting_ip",
						"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
						"description": "My first response header transform rule",
						"action": "rewrite",
						"action_parameters": {
								"headers": {
										"cf-connecting-ip": {
												"operation": "remove"
										}
								}
						}
				}
		]
	}'
{
	"result": {
		"id": "<RULESET_ID>",
		"name": "Zone-level Response Headers Transform Ruleset",
		"description": "Zone-level ruleset that will execute Response Header Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"ref": "remove_resp_header_cf_connecting_ip",
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"headers": {
						"cf-connecting-ip": {
							"operation": "remove"
						}
					}
				},
				"expression": "(starts_with(http.request.uri.path, \"/en/\"))",
				"description": "My first response header transform rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_response_headers_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

使用 Terraform 时,通过 ref 字段使规则 ID 在更新之间保持稳定。添加此字段可防止 Terraform 在发生变更时重新创建规则。更多信息请参阅 Terraform 文档中的故障排除。


所需的 API 令牌权限

用于管理响应头转换规则的 API 请求的 API 令牌至少须具备以下权限:

  • 转换规则 > 编辑
  • 账户规则集 > 读取

这篇文档对您有帮助吗?