API 架构(schema)根据目标端点、路径或查询变量格式以及 HTTP 方法等多个请求属性,定义哪些 API 请求是有效的。
架构验证会将传入请求与已上传的 OpenAPI 架构进行比较。已上传的架构为 Schema Profile 提供预期的请求结构。
已上传配置文件可用后,Cloudflare 会生成始终开启的检测。使用 cf.schema_validation.uploaded.violated 来分析和缓解违规。
该检测本身不会缓解流量。请先在配置文件分析中审查结果,然后再使用自定义规则强制执行配置文件。
架构验证 2.0 是当前版本。上一版本的参考请参阅配置经典架构验证。
端点必须作为已保存操作存在于 Web Assets(Web 资产) > Operations(操作) 中。通过仪表板上传会自动添加架构操作。
使用 API 或 Terraform 时,请单独添加架构操作。自动化详情请参阅 API 配置 或 Terraform。
-
在 Cloudflare 仪表板中,前往 Web Assets(Web 资产) 页面。
前往 Web assets(Web 资产) ↗ -
前往 Schema validation(架构验证) 选项卡。
-
选择 Add validation(添加验证)。
-
上传 OpenAPI 架构文件。
-
选择 Add schema and endpoints(添加架构和端点)。
更改可能需要几分钟,具体取决于操作数量。
可以同时启用多个已上传的架构。当新架构包含已被活动架构覆盖的操作时,新架构仅会替换该操作的验证定义。未包含在新架构中的操作会继续使用其现有验证定义。
-
在 Cloudflare 仪表板中,前往 Web Assets(Web 资产) 页面。
前往 Web assets(Web 资产) ↗ -
前往 Schema validation(架构验证) 选项卡。
-
选择 Schema settings(架构设置)。
-
按 API 滥用 过滤。
-
在 Schema validation(架构验证) > Active schemas(活动架构) 下审查已上传的架构。
-
从架构的更多选项菜单中下载或删除该架构。
删除已上传的架构会停止其配置文件评估。关联操作仍会保留在 Web 资产清单中。
兜底规则匹配未匹配已保存操作的请求。匹配候选操作的请求也会匹配兜底规则。使用此 WAF 自定义规则来防护未识别的端点。
-
在 Cloudflare 仪表板中,前往安全 规则 页面。
前往 Security rules(安全规则) ↗ -
选择 Templates(模板)。
-
找到
Mitigate API requests to unidentified endpoints并选择 Preview template(预览模板)。 -
输入描述性规则名称。
-
选择目标主机名和规则操作。
-
选择 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 客户的限制,请参阅套餐。
架构验证在所列上下文中需要以下字段。它可以按本节所述推断某些参数架构类型。
type↗- 除非架构验证可以从
items、properties、单一类型的enum值或无歧义的组合分支推断出类型,否则参数架构需要受支持的类型。如果架构验证不支持该特定类型,请将该类型改设为string。
- 除非架构验证可以从
schema↗- 架构验证不支持参数中的 content 字段。更多详情请参阅下面有关已验证和支持字段的说明。相反,所有参数对象都严格需要一个架构。
请参阅以下信息,了解有关架构验证目前对各种 OpenAPI 规范 (OAS) 对象和字段支持的更多详细信息。
url↗- 架构验证不支持相对 URL。
variables↗- 服务器变量不被验证。
style↗- 仅支持默认值:
"simple"(路径或标头参数)和"form"(查询或 cookie 参数)。
- 仅支持默认值:
explode↗- 仅支持默认值:
true(对于 form)和false(对于 simple)。
- 仅支持默认值:
content↗- 参数中不支持 content 字段。请改用 schema 字段。
type↗- Cloudflare 目前不验证对象类型的参数。
$ref↗- 支持本地组件引用,例如
#/components/schemas/Pet。不支持外部引用和其他相对引用。在上传包含不受支持引用的架构之前,请使用 OpenAPI 打包工具(例如 Redocly CLIbundle命令 ↗)将其转换为单文件架构。
- 支持本地组件引用,例如
content- Request Body Object ↗
- Media Type Object ↗
- 架构验证可以验证
application/json以及兼容的application/x-www-form-urlencoded文档。如果架构允许其他内容类型,架构验证会在不进行正文验证的情况下接受这些请求。
- 架构验证可以验证
anyOf- Parameter Object ↗
- Schema Object ↗
- 参数架构中目前不支持
anyOf架构。
- 参数架构中目前不支持
format↗- 已验证的格式:
date-timetimedateemailhostnameipv4ipv6uriuri-referenceiriiri-referenceint32int64floatdoublepassworduuidbyteuint64
- 已验证的格式:
pattern↗- 模式遵循 Rust
regexcrate 第 1 版文档中的语法 ↗。不受支持的构造包括 look-around 和反向引用。无效或不受支持的模式会导致架构上传失败。
- 模式遵循 Rust
uniqueItems↗- 架构验证目前不验证此字段。
API Shield 会根据匹配的正文架构验证传入请求正文。架构验证支持 application/json 以及兼容的 application/x-www-form-urlencoded 正文。
Cloudflare 允许在 OpenAPI 请求正文内容映射中指定以下媒体范围:
*/*application/*application/jsonapplication/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 ↗ 选项。
由于以下两个原因之一,请求是无效的:
- Matches Zero(匹配数量为零):有效负载与任何可用的子架构均不正确匹配。当设置了鉴别器字段,但有效负载缺少该类型的其他必需字段时,这是很常见的。
- Matches Multiple(匹配多个):有效负载是模糊的,并且匹配了多个子架构。对于通用架构(例如,如果有效负载同时包含
email和phone字段,它可能同时匹配email和phone架构定义,从而违反了“精确匹配其中一个”的规则),就会发生这种情况。
要解决此问题,请将抽样请求与其架构定义进行比较。请求可能省略了必需字段,或匹配了冲突的类型。
已拥有 API Security 的客户已可通过架构学习和架构验证使用 Schema Profile。Cloudflare 正在向未使用 API Security 的受邀企业版客户开放封闭 Beta。有兴趣的客户可联系账户团队表达意向。封闭 Beta 访问权限并不意味着未来的套餐可用性或定价。