使用 API 创建速率限制规则集

要在账户级部署速率限制规则，您必须创建一个包含一条或多条规则的速率限制规则集。使用 Rulesets API，通过 API 创建和部署速率限制规则集。

有关规则参数的更多信息，请参阅 速率限制参数。

每条速率限制规则都包含一个用于设置速率限制配置的 ratelimit 对象。有关此对象及其参数的更多信息，请参阅 速率限制参数。

如果您使用的是 Terraform，请参阅 使用 Terraform 配置速率限制规则。

要在您的账户中部署速率限制规则集，请遵循以下通用步骤：

1. 在 http_ratelimit 阶段中创建一个包含一条或多条速率限制规则的速率限制规则集（即自定义规则集）。
2. 将规则集部署到账户级 http_ratelimit 阶段的 入口点规则集。

以下示例创建了一个速率限制规则集，其 rules 数组中包含单条速率限制规则。

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"description": "",
		"kind": "custom",
		"name": "My rate limiting ruleset",
		"rules": [
				{
						"description": "Rate limit API requests",
						"expression": "(starts_with(http.request.uri.path, \"/my-api/\"))",
						"ratelimit": {
								"characteristics": [
										"ip.src",
										"cf.colo.id"
								],
								"requests_to_origin": false,
								"requests_per_period": 30,
								"period": 60,
								"mitigation_timeout": 120
						},
						"action": "block",
						"action_parameters": {
								"response": {
										"status_code": 429,
										"content_type": "application/json",
										"content": "{ \"error\": \"Your API requests have been rate limited. Wait a couple of minutes and try again.\" }"
								}
						},
						"enabled": true
				}
		],
		"phase": "http_ratelimit"
	}'

可用的特征（characteristics）取决于您的 Cloudflare 计划和产品订阅。有关更多信息，请参阅 可用性。

保存响应中的规则集 ID，以便在下一步中使用。

要部署速率限制规则集，请在账户级将一条具有 "action": "execute" 的规则添加到 http_ratelimit 阶段入口点规则集。

1. 调用获取账户入口点规则集操作，以获取 http_ratelimit 阶段的入口点规则集定义。您将需要账户 ID来执行此任务。

   Required API token permissions

   At least one of the following token permissions is required:

   • Account WAF Write
   • Account WAF Read
   • Account Rulesets Read
   • Account Rulesets Write

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/phases/http_ratelimit/entrypoint" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   {
   	"result": {
   		"description": "Account-level phase entry point",
   		"id": "<RULESET_ID>",
   		"kind": "root",
   		"last_updated": "2024-03-16T15:40:08.202335Z",
   		"name": "root",
   		"phase": "http_ratelimit",
   		"rules": [
   			// ...
   		],
   		"source": "firewall_managed",
   		"version": "10"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }

2. 如果入口点规则集已存在（即，如果您收到 200 OK 状态代码和规则集定义），请记下响应中的规则集 ID。然后，调用创建账户规则集规则操作，向现有规则集中添加一条 execute 规则，以部署 rate limiting ruleset。默认情况下，该规则将添加到规则集中已有规则列表的末尾。

   以下请求创建了一条规则，该规则针对账户中的所有 Enterprise zone 执行 ID 为 <RATE_LIMITING_RULESET_ID> 的速率限制规则集：

   Required API token permissions

   At least one of the following token permissions is required:

   • Account WAF Write
   • Account Rulesets Write

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID/rules" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"description": "Execute rate limiting ruleset",
   		"expression": "(cf.zone.plan eq \"ENT\")",
   		"action": "execute",
   		"action_parameters": {
   				"id": "<RATE_LIMITING_RULESET_ID>"
   		},
   		"enabled": true
   	}'

3. 如果入口点规则集不存在（即，如果您在第 1 步中收到 404 Not Found 状态代码），请使用创建账户规则集操作来创建它。在 rules 数组中包含一条单一规则，以便为 all incoming requests of Enterprise zones in your account 执行 rate limiting ruleset。

   Required API token permissions

   At least one of the following token permissions is required:

   • Account WAF Write
   • Account Rulesets Write

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"description": "",
   		"kind": "root",
   		"name": "Account-level phase entry point",
   		"rules": [
   				{
   						"action": "execute",
   						"expression": "(cf.zone.plan eq \"ENT\")",
   						"action_parameters": {
   								"id": "<CUSTOM_RULESET_ID>"
   						}
   				}
   		],
   		"phase": "http_ratelimit"
   	}'

有关 API 的速率限制规则定义示例，请参阅 通过 API 创建速率限制规则。

使用 Rulesets API 中的不同操作来处理您刚刚创建并部署的规则集。下表列出了在账户级处理速率限制规则集的常见任务：

有关如何通过 API 在 zone 级部署速率限制规则的说明，请参阅 通过 API 创建速率限制规则。

有关可在速率限制规则中配置的不同速率限制参数的更多信息，请参阅 速率限制参数。