跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

通过 API 配置架构验证

最后更新 查看 MarkdownAgent 设置

架构验证 2.0 允许通过 API 进行所有相应的配置调用。此验证更多地围绕单个端点展开，并允许您单独为每个端点设置缓解操作。此外，您可以使用 Cloudflare 提供的学习到的架构，这些架构是我们在个别端点上根据您的流量自动学习到的。

通过 API 上传架构到架构验证

  1. 上传架构。
  2. 确保您的端点已添加到端点管理中。
  3. 如果尚未将架构设置为 active，请进行设置。
  4. 将架构验证的区域级操作从 none 更改为 log。
  5. 发送违反架构的测试流量。
  6. 通过筛选 Service（服务） > API Shield - 架构验证 来在安全事件中查看测试流量。
  7. 可选操作：
    • 将单个端点设置为 block。
    • 将区域级架构验证设置为 block。
    • 临时将所有架构的区域级操作覆盖为 none。
    • 删除临时覆盖。

Cloudflare 建议您在更改任何设置后重新运行测试流量并监控 HTTP 响应代码，以确保架构验证按预期运行。

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

配置

上传并激活架构

使用 POST 通过 v4 API 上传架构。本示例要求在当前文件夹中有一个 example_schema.yaml 架构文件。

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": true
	}'
{
    "result":
    {
        "schema":
        {
            "schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
            "name": "example_schema",
            "kind": "openapi_v3",
            "source": "<SOURCE>",
            "created_at": "2023-04-03T15:10:08.902309Z"
        }
    },
    "success": true,
    "errors":
    [],
    "messages":
    []
}

默认情况下，对上传的架构禁用架构验证，以便您可以先对其进行检查。您可以通过将表单参数设置为 validation_enabled=true 来上传架构并立即启用它。

检查后，使用 PATCH 请求激活架构。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Enable validation for a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/api_gateway/user_schemas/$SCHEMA_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"validation_enabled": true
	}'
{
    "result":
    {
        "schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0",
        "name": "api_schema.json",
        "kind": "openapi_v3",
        "validation_enabled": true,
        "created_at": "0001-01-01T00:00:00Z"
    },
    "success": true,
    "errors":
    [],
    "messages":
    []
}

当架构处于活动状态时，它会执行为每个操作指定的缓解操作。请参阅更改默认和特定于操作的缓解操作。

向端点管理添加新操作

架构包含一组服务器、路径和方法，它们共同定义了一个操作。架构验证仅对已添加到 API Shield 端点管理的请求操作起作用。如果架构包含未添加到端点管理的操作，它们可以与关于已添加操作的配置信息一起被获取。

cURL 命令bash
curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json'
{
    "result":
        [
          {
              "method": "GET",
              "host": "example.com",
              "endpoint": "/pets"
          }
      ],
    "success": true,
    "errors": [],
    "messages": [],
    "result_info": {
        "page": 1,
        "per_page": 30,
        "count": 1,
        "total_count": 1
    }
}

要接收有关现有操作配置的信息，Cloudflare 建议传递 ?feature=schema_info 参数。

您可以使用 POST 向端点管理添加架构中的新操作。

cURL 命令bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <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":
    []
}

您可以通过将两个命令组合为一个，将架构中尚不存在于端点管理中的所有操作添加进来。此 API 调用的操作上限为 20 个。该示例需要使用 jq 工具。

cURL 命令bash
curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data "$(curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&page=1&per_page=5000" --header "Authorization: Bearer <API_TOKEN>" | jq ".result")"

更改默认和特定于操作的缓解操作

如果某个架构已上传并且对一组操作处于活动状态，它将验证发往每个操作的传入请求，并决定是否应采取缓解操作。此缓解操作是针对每个操作定义的，其值可以为 none、log 和 block，分别对应于不采取操作、记录请求或在请求到达源站之前阻止它们。

新操作将不会设置缓解操作，并将使用区域级的默认缓解操作。当前的默认缓解操作可以使用 GET 获取。

cURL 命令bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>"
{
    "result":  {
        "validation_default_mitigation_action": "none",
        "validation_override_mitigation_action": null
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

可以使用 PUT 设置自 none、log 和 block 中的新值。

cURL 命令bash
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "validation_default_mitigation_action": "block"
}'
{
    "result":  {
        "validation_default_mitigation_action": "block",
        "validation_override_mitigation_action": null
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

如果对单个操作的缓解操作感兴趣，可以使用操作 ID 通过 GET 获取当前值。

cURL 命令bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>"
{
    "result":  {
        "mitigation_action": "null"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

如果值为 null，这意味着没有为该操作指定缓解操作，并且正在使用默认的缓解操作。

您可以通过使用 PUT 将缓解操作设置为 none、block、log 和 null 之一。

cURL 命令bash
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
    "mitigation_action": "block"
}'
{
    "result":  {
        "mitigation_action": "block"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

列出所有架构

您可以使用 GET 获取当前在一个区域上处于活动状态的架构概述。

validation_enabled=true 是一个可选参数。

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>",
	        "created_at": "2023-04-03T15:10:08.902309Z"
	    }
    ]
    "success": true,
    "errors":
    [],
    "messages":
    []
}

删除架构

您可以使用 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":
    []
}

激活操作的学习到的架构

Cloudflare 为端点管理中所有拥有足够请求量的操作提供自动学习的参数架构。可以使用 GET 检查学习到的架构。

cURL 命令bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}?feature=parameter_schemas" \
--header "Authorization: Bearer <API_TOKEN>"
{
    "result":
    {
        "operation_id": "5c734fcd-455d-4040-9eaa-dbb3830526ae",
        "method": "PATCH",
        "host": "example.com",
        "endpoint": "/pets",
        "last_updated": "2023-04-04T16:07:37.575971Z",
        "features":
        {
            "parameter_schemas":
            {
                "last_updated": "2023-04-03T20:11:55.879006Z",
                "parameter_schemas":
                {
                    "responses": null,
                    "parameters":
                    [
                        {
                            "in": "query",
                            "name": "var1",
                            "schema":
                            {
                                 "type": "string"
                            },
                            "required": true,
                            "description": "Sufficient requests have been observed for this parameter to provide high confidence in this parameter schema."
                        }
                    ],
                    "x-cf-parameter-schemas": "operation schema with automatically learned path and query parameters"
                }
            }
        }
    },
    "success": true,
    "errors":
    [],
    "messages":
    []
}

如果您对检查的参数架构感到满意，可以使用 PUT 添加并激活它。

cURL 命令bash
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/cloudflare_learned_schema?timestamp=2023-04-03T20:11:55.879006Z" \
--header "Authorization: Bearer <API_TOKEN>"
{
    "result": null,
    "success": true,
    "errors":
    [],
    "messages":
    []
}

禁用架构验证

要为整个区域快速禁用架构验证，请使用 PATCH。此操作将覆盖所有的操作缓解动作。

cURL 命令bash
curl --request PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '{
  "validation_override_mitigation_action": "none"
}'
{
    "result":  {
        "validation_default_mitigation_action": "block",
        "validation_override_mitigation_action": "none"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

这篇文档对您有帮助吗？