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

API 配置

最后更新 查看 MarkdownAgent 设置

使用 API 上传、激活、列出和删除 OpenAPI 架构。已上传的架构会为其操作提供 Schema Profile。

配置已上传的架构

  1. 上传架构,并将 validation_enabled 设置为 false。
  2. 将架构操作添加为 Web 资产清单中的已保存操作。
  3. 通过将 validation_enabled 设置为 true 来激活架构。
  4. 通过已配置的操作发送代表性流量。
  5. 在配置文件分析中分析 cf.schema_validation.uploaded.violated。
  6. 使用 WAF 自定义规则配置缓解。

设置更改可能需要几分钟才能实施。

配置

上传架构

使用 POST 上传架构。在配置操作时保持验证处于未启用状态。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Upload a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"kind": "openapi_v3",
		"name": "example_schema",
		"source": "<SOURCE>",
		"validation_enabled": false
	}'
{
	"result": {
		"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
		"name": "example_schema",
		"kind": "openapi_v3",
		"source": "<SOURCE>",
		"validation_enabled": false,
		"created_at": "2023-04-03T15:10:08.902309Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

添加架构操作

架构包含定义操作的主机、路径和方法。操作按 HTTP 方法、主机名模式和路径模式表示一个端点。

架构验证仅评估 Web 资产中已保存操作的请求。使用 GET 从架构中检索操作。

cURL commandbash
curl --request GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID/operations?operation_status=new&page=1&per_page=50" \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": [
		{
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 50,
		"count": 1,
		"total_count": 1
	}
}

使用 operation_status=new 返回尚未保存的操作。使用 feature=schema_info 可包含现有操作的架构验证配置。

结果会分页。请请求每一页以检索所有架构操作。

使用 POST 将架构操作添加到 Web 资产。

cURL commandbash
curl --request POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/api_gateway/operations" \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--header "Content-Type: application/json" \
	--data '[
		{
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets"
		}
	]'
{
	"result": [
		{
			"operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae",
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets",
			"last_updated": "2023-04-04T16:07:37.575971Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

该端点可能会限制单次批处理中可添加的操作数量。如有必要,请分多个请求添加操作。

激活架构

保存操作后,使用 PATCH 激活架构。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Set schema validation statebash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"validation_enabled": true
	}'
{
	"result": {
		"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
		"name": "example_schema",
		"kind": "openapi_v3",
		"source": "",
		"validation_enabled": true,
		"created_at": "2023-04-03T15:10:08.902309Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

激活会使已上传配置文件评估对已配置操作可用。

列出所有架构

使用 GET 列出某个 zone 上已上传的架构。结果使用相同的 page 和 per_page 分页参数。

使用可选的 validation_enabled 查询参数按验证状态过滤架构。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Account API Gateway Read
  • Domain API Gateway
  • Domain API Gateway Read
List all uploaded schemasbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": [
		{
			"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
			"name": "example_schema",
			"kind": "openapi_v3",
			"source": "<SOURCE>",
			"validation_enabled": true,
			"created_at": "2023-04-03T15:10:08.902309Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 20,
		"count": 1,
		"total_count": 1
	}
}

删除架构

您可以使用 DELETE 删除架构。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Delete a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

这篇文档对您有帮助吗?