架构验证

The API schema defines which API requests are valid based on several request properties like target endpoint, path or query variable format, and HTTP method.

架构验证 (Schema validation) 允许您检查传入的流量是否符合以前提供的 API 架构。当您提供 API 架构或从学习到的架构列表中进行选择时，API Shield 会根据该架构定义为传入的流量创建规则。这些规则定义了允许哪些流量，以及对哪些流量进行记录或阻止。

架构验证 2.0 是当前版本。要获取使用仪表板为多个主机配置上一版本的帮助，请参阅配置经典架构验证。您可以更改经典架构验证的设置，但无法添加任何新架构。

您可以通过将架构上传到新系统中，手动迁移到架构验证 2.0。

必须将端点添加到端点管理中才能通过架构验证来保护它们。通过 Cloudflare 仪表板上传架构将自动添加端点，或者您也可以从 API 发现中手动添加它们。

如果您是通过 API 或 Terraform 上传架构，您必须解析架构并手动添加端点。

The API endpoint is the location where API calls or requests are fulfilled. API Shield defines endpoints as a host, method, and path tuple.

目前，学习到的架构不会覆盖客户上传的架构。如果某个端点已被客户上传的架构覆盖，并且也出现在学习到的架构中，则 Changes（更改） 字段将被设置为 未受影响 (Unaffected)。

兜底规则 (fallthrough rule) 用作针对不匹配端点管理中端点请求的捕获规则。

通过确保您架构中的所有端点都已添加到端点管理中，兜底操作可以保护您免受您的团队可能不了解的遗留端点或僵尸端点的影响。

要设置兜底操作：

架构验证的默认操作在架构验证主页面上可见。此操作适用于其操作被设置为 默认 (Default) 的任何端点。

• 记录 (Log) 操作：将事件记录到防火墙事件 (Firewall Events)。
• 阻止 (Block) 操作：阻止端点中未能通过架构验证的请求，并将事件记录到防火墙事件 (Firewall Events)。
• 无 (None) 操作：不合规请求既不被记录也不被阻止。

要更改默认操作：

您可以在架构验证中将单个端点的操作与默认操作分开更改。

这允许您在默认操作为 Log 时，对某些端点上的不合规请求采取更严格的阻止操作。它也可以用于在默认操作设置为 Block 时，放宽对某些端点上不合规请求的限制。您可能希望通过将操作设置为 None 来消除端点上的已知误报。

要更改单个端点上的操作：

您可以完全禁用架构验证以进行临时故障排除。您可以一次性覆盖所有操作，在您完成故障排除时防止架构验证采取任何操作。

要在不更改操作的情况下禁用架构验证：

修改该设置时，您的每个端点配置都将被保存，这样您就不会丢失配置。要在故障排除后重新启用您的配置，请导航回设置并选择 Enable（启用）。

删除架构将从当前关联的端点中删除验证，但不会从端点管理中删除端点。

要删除当前上传的或学习到的架构：

Cloudflare 目前仅接受 OpenAPI v3 架构 ↗。接受的文件格式为 YAML（.yml 或 .yaml 文件扩展名）和 JSON（.json 文件扩展名）。

由不同工具生成的 OpenAPI 架构可能不够具体，无法导入到架构验证中。请使用第三方工具（例如 Swagger Editor ↗）以确保架构符合 OpenAPI 规范。

Cloudflare API Shield 的架构验证（导入）和架构学习（导出）能力依赖于 OpenAPI 规范 (OAS) v3.0 ↗。

此支持包括所有补丁版本，例如 OAS v3.0.x。不支持 OAS v3.1，目前没有计划扩展对 OpenAPI 2.0 的支持。

目前，API Shield 不支持 API 架构的某些功能，包括以下内容：所有响应、外部引用、非基本路径模板化或唯一项。

对于订阅了 API Shield 的企业版客户，已启用的架构总共有 10,000 次操作的限制。要提高此限制，请联系您的账户团队。

架构验证检查请求正文的最大大小取决于您的区域套餐。超过此限制的请求正文将不针对您的架构进行验证，且配置的架构验证操作将不适用于这些请求。

默认的正文大小限制为：

如果架构验证由于正文大小限制而阻止或记录请求，您将在 Security（安全性） > Events（事件） 中看到以架构验证规则为数据源的事件。

有关未订阅 API Shield 的免费版、专业版、商业版或企业版客户的限制，请参阅套餐。

虽然 OpenAPI 规范没有严格要求，但架构验证严格要求这些字段。

• type ↗
  • 所有架构都需要设置类型。如果架构验证不支持该特定类型，请将该类型改设为 string。

• schema ↗
  • 架构验证不支持参数中的 content 字段。更多详情请参阅下面有关已验证和支持字段的说明。相反，所有参数对象都严格需要一个架构。

请参阅以下信息，了解有关架构验证目前对各种 OpenAPI 规范 (OAS) 对象和字段支持的更多详细信息。

• url ↗
  • 架构验证不支持相对 URL。
• variables ↗
  • 服务器变量不被验证。

• style ↗
  • 仅支持默认值："simple"（路径或标头参数）和 "form"（查询或 cookie 参数）。
• explode ↗
  • 仅支持默认值：true（对于 form）和 false（对于 simple）。
• content ↗
  • 参数中不支持 content 字段。请改用 schema 字段。
• type ↗
  • Cloudflare 目前不验证对象类型的参数。

• $ref ↗
  • 不支持外部引用或相对引用。

• content
  • Request Body Object ↗
  • Media Type Object ↗
    • 架构验证能够验证 application/json 文档。如果给定的架构允许其他内容类型，架构验证将接受这些请求而不进行验证。

• anyOf
  • Parameter Object ↗
  • Schema Object ↗
    • 参数架构中目前不支持 anyOf 架构。

• format ↗

  • 已验证的格式：
    • date-time
    • time
    • date
    • email
    • hostname
    • ipv4
    • ipv6
    • uri
    • uri-reference
    • iri
    • iri-reference
    • int32
    • int64
    • float
    • double
    • password
    • uuid
    • byte
    • uint64

• uniqueItems ↗

  • 架构验证目前不验证此字段。

API Shield 能够识别上传架构中包含的正文规范，并验证传入 API 请求的数据是否符合这些规范。

架构验证目前支持验证内容类型为 application/json 的请求。

在 OpenAPI 规范中，请求正文架构与媒体范围（例如 application/*、application/xml 或 application/json）相关联。

当 Cloudflare 验证传入请求时，Cloudflare 会检查请求的 content-type 是否与 OpenAPI 指定的媒体范围相匹配。

例如，当 OpenAPI 文件将 application/* 指定为请求正文内容映射的一部分时，Cloudflare 将接受内容类型为 application/xml 和 application/json 的请求。然而，只有 application/json 正文会使用提供的架构进行验证。

Cloudflare 建议通过将媒体范围设置为单个媒体类型，来使其尽可能严紧。如果您需要在 API 端点上支持多种内容类型，您可以使用通配符媒体范围。

如果源站配置为执行 MIME 嗅探 (MIME sniffing) ↗，也应当小心。例如，当携带 JSON 正文的请求故意携带 application/malicious 内容类型，且 Cloudflare 被配置为允许 application/* 媒体范围时，该请求将被传递到源站，而不验证 JSON 正文内容。然而，忽略内容类型并尝试反序列化或嗅探 MIME 类型的源站可能会反序列化 JSON 正文，并错误地假设其已通过架构正文验证。

因此，如果您需要在同一端点上支持 application/json 和 application/xml，您可以使用 application/*。Cloudflare 将针对内容类型设置为 application/json 的请求正文验证所提供的架构。内容类型为 application/xml（以及其他匹配 application/* 的内容类型）的请求将被允许通过。仍然强烈建议在您的源站上禁用内容类型嗅探。

Cloudflare 允许在 OpenAPI 请求正文内容映射中指定以下媒体范围：

• */*
• application/*
• application/json。

媒体范围也可以配置为强制执行 charset 参数。为此，Cloudflare 仅接受 charset 参数作为媒体范围规范的一部分，且具有静态值 utf-8，并且在配置时，我们将类似地要求请求的 content-type 携带此字符集。

本节解决您在使用架构验证时可能遇到的常见问题。

OneOf 约束错误意味着 API 请求未通过架构验证，因为其正文与您上传的架构中的 oneOf ↗ 列表里定义的选项没有精确匹配其中一个。

由于以下两个原因之一，请求是无效的：

• Matches Zero（匹配数量为零）：有效负载与任何可用的子架构均不正确匹配。当设置了鉴别器字段，但有效负载缺少该类型的其他必需字段时，这是很常见的。
• Matches Multiple（匹配多个）：有效负载是模糊的，并且匹配了多个子架构。对于通用架构（例如，如果有效负载同时包含 email 和 phone 字段，它可能同时匹配 email 和 phone 架构定义，从而违反了“精确匹配其中一个”的规则），就会发生这种情况。

要解决此问题，请根据 API 架构定义检查失败的请求正文。它要么缺少目标类型的必需字段，要么包含来自多个不同的、相互冲突的属性，从而使其变得模糊。

所有客户均可使用架构验证。有关更多信息，请根据您的套餐类型参阅套餐。

架构学习仅适用于订阅了 API Shield 的客户。