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

使用 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 时，请遵循以下工作流：

使用 List zone rulesets 操作检查 zone 级别是否已有 http_response_headers_transform phase 的 ruleset。
如果 phase ruleset 不存在，使用 Create a zone ruleset 操作创建。在新 ruleset 属性中设置以下值：
- kind：zone
- phase：http_response_headers_transform
使用 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": []
}

示例：添加带静态值的 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": []
}

示例：移除 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": []
}

所需的 API 令牌权限

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

Transform Rules > Edit
Account Rulesets > Read