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

架构验证

最后更新 查看 MarkdownAgent 设置

API 架构(schema)根据目标端点、路径或查询变量格式以及 HTTP 方法等多个请求属性,定义哪些 API 请求是有效的。

架构验证会将传入请求与已上传的 OpenAPI 架构进行比较。已上传的架构为 Schema Profile 提供预期的请求结构。

已上传配置文件可用后,Cloudflare 会生成始终开启的检测。使用 cf.schema_validation.uploaded.violated 来分析和缓解违规。

该检测本身不会缓解流量。请先在配置文件分析中审查结果,然后再使用自定义规则强制执行配置文件。

架构验证 2.0 是当前版本。上一版本的参考请参阅配置经典架构验证。

配置已上传的架构

端点必须作为已保存操作存在于 Web Assets(Web 资产) > Operations(操作) 中。通过仪表板上传会自动添加架构操作。

使用 API 或 Terraform 时,请单独添加架构操作。自动化详情请参阅 API 配置 或 Terraform。

上传架构

  1. 在 Cloudflare 仪表板中,前往 Web Assets(Web 资产) 页面。

    前往 Web assets(Web 资产) ↗
  2. 前往 Schema validation(架构验证) 选项卡。

  3. 选择 Add validation(添加验证)。

  4. 上传 OpenAPI 架构文件。

  5. 选择 Add schema and endpoints(添加架构和端点)。

更改可能需要几分钟,具体取决于操作数量。

可以同时启用多个已上传的架构。当新架构包含已被活动架构覆盖的操作时,新架构仅会替换该操作的验证定义。未包含在新架构中的操作会继续使用其现有验证定义。

管理已上传的架构

  1. 在 Cloudflare 仪表板中,前往 Web Assets(Web 资产) 页面。

    前往 Web assets(Web 资产) ↗
  2. 前往 Schema validation(架构验证) 选项卡。

  3. 选择 Schema settings(架构设置)。

  4. 按 API 滥用 过滤。

  5. 在 Schema validation(架构验证) > Active schemas(活动架构) 下审查已上传的架构。

  6. 从架构的更多选项菜单中下载或删除该架构。

删除已上传的架构会停止其配置文件评估。关联操作仍会保留在 Web 资产清单中。

添加兜底规则

兜底规则匹配未匹配已保存操作的请求。匹配候选操作的请求也会匹配兜底规则。使用此 WAF 自定义规则来防护未识别的端点。

  1. 在 Cloudflare 仪表板中,前往安全 规则 页面。

    前往 Security rules(安全规则) ↗
  2. 选择 Templates(模板)。

  3. 找到 Mitigate API requests to unidentified endpoints 并选择 Preview template(预览模板)。

  4. 输入描述性规则名称。

  5. 选择目标主机名和规则操作。

  6. 选择 Save as draft(保存为草稿) 或 Deploy(部署)。

对于自定义逻辑,请使用 cf.api_gateway.fallthrough_detected。将规则限定到您的 API 主机名或根路径。


规范

Cloudflare 接受 OpenAPI v3.0 架构 ↗。当 OpenAPI v3.1 上传使用与 v3.0 兼容的语义时可以成功。不支持仅属于 OpenAPI v3.1 的语义。接受的文件格式为 YAML(.yml 或 .yaml 文件扩展名)和 JSON(.json 文件扩展名)。

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


限制

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

此支持包括所有补丁版本,例如 OAS v3.0.x。Cloudflare 会使用 v3.0 语义处理兼容的 OAS v3.1 上传,但不支持仅属于 v3.1 的语义。不支持 OpenAPI 2.0。

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

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

验证的正文大小

架构验证会按套餐特定的最大大小对请求正文进行结构化检查。对于具有适用正文架构的操作,过大的正文会产生架构验证正文大小违规。

默认的正文大小限制为:

套餐 默认正文大小限制
Free 1 KiB
Pro 8 KiB
Business 8 KiB
Enterprise 128 KiB

识别超过正文大小限制的请求

使用请求日志将正文大小与您的套餐限制进行比较。

有关未订阅 API Shield 的 Free、Pro、Business 或 Enterprise 客户的限制,请参阅套餐。

必需字段

架构验证在所列上下文中需要以下字段。它可以按本节所述推断某些参数架构类型。

schema

  • type ↗
    • 除非架构验证可以从 items、properties、单一类型的 enum 值或无歧义的组合分支推断出类型,否则参数架构需要受支持的类型。如果架构验证不支持该特定类型,请将该类型改设为 string。

parameter

有关已验证和支持字段的说明

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

servers

parameter

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

reference

  • $ref ↗
    • 支持本地组件引用,例如 #/components/schemas/Pet。不支持外部引用和其他相对引用。在上传包含不受支持引用的架构之前,请使用 OpenAPI 打包工具(例如 Redocly CLI bundle 命令 ↗)将其转换为单文件架构。

requestBody

  • content
    • Request Body Object ↗
    • Media Type Object ↗
      • 架构验证可以验证 application/json 以及兼容的 application/x-www-form-urlencoded 文档。如果架构允许其他内容类型,架构验证会在不进行正文验证的情况下接受这些请求。

parameter/schema

schema


正文检查

API Shield 会根据匹配的正文架构验证传入请求正文。架构验证支持 application/json 以及兼容的 application/x-www-form-urlencoded 正文。

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

  • */*
  • application/*
  • application/json
  • application/x-www-form-urlencoded

通配符媒体范围可以允许其他内容类型而不验证其正文结构。例如,application/* 允许 application/xml,但架构验证不会对 XML 正文进行结构化验证。请尽可能具体地设置媒体范围,并在源站禁用 MIME 嗅探 (MIME sniffing) ↗。

表单编码正文

要验证表单正文,请显式定义 application/x-www-form-urlencoded。其顶层架构必须是对象。属性可以是基元或基元的扁平数组。Cloudflare 不会应用包含嵌套对象、嵌套数组、byte 或 binary 格式,或非默认编码指令的表单正文架构。

表单字段名称和值必须解码为有效的 UTF-8。重复某个键以提供数组值。标量键只能出现一次,而数组出现一次是有效的。一个表单正文最多可以包含 8,192 个键值对。额外的对会产生正文违规。

对于已验证的 JSON 和表单请求,charset 是可选的,并且是唯一接受的媒体类型参数。如果存在,其值必须为 utf-8。已上传架构中的 charset 参数并不要求请求包含它。


故障排除

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

解决 OneOf 约束违规

OneOf 约束错误表示请求违反了其已上传的配置文件。其正文没有精确匹配其中一个 oneOf ↗ 选项。

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

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

要解决此问题,请将抽样请求与其架构定义进行比较。请求可能省略了必需字段,或匹配了冲突的类型。


可用性

已拥有 API Security 的客户已可通过架构学习和架构验证使用 Schema Profile。Cloudflare 正在向未使用 API Security 的受邀企业版客户开放封闭 Beta。有兴趣的客户可联系账户团队表达意向。封闭 Beta 访问权限并不意味着未来的套餐可用性或定价。

这篇文档对您有帮助吗?