<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
OASValidation 政策简介
借助 OASValidation(OpenAPI 规范验证)政策,您可以根据 OpenAPI 3.0 规范(JSON 或 YAML)验证传入请求或响应消息。请参阅验证哪些内容?
在政策附加到的步骤执行时,OASValidation 政策指定用于验证的 OpenAPI 规范的名称。
OpenAPI 规范作为资源存储在 API 代理软件包中的以下标准位置:apiproxy/resources/oas
。OpenAPI 规范必须具有 .json
、.yml
、.yaml
扩展名。
使用界面或 API 将 OpenAPI 规范作为资源添加到 API 代理软件包,如管理资源中所述。
验证哪些内容?
下表总结了 OASValidation 政策验证的请求消息内容,按组件划分。
组件 | 请求验证 |
---|---|
基本路径 | 验证 API 代理定义的基本路径;忽略 OpenAPI 规范中指定的基准路径。 |
路径 | 验证请求路径(去掉基本路径)是否与 OpenAPI 规范中定义的某一路径模式匹配。 |
动词 | 验证是否已在 OpenAPI 规范中为路径定义该动词。 |
请求消息正文 |
注意:仅在 Content-Type 设置为 |
参数 |
|
下表总结了 OASValidation 政策验证的响应消息内容,按组件划分。
组件 | 回复验证 |
---|---|
路径 | 验证请求路径(去掉基本路径)是否与 OpenAPI 规范中定义的某一路径模式匹配。 |
动词 | 验证是否已在 OpenAPI 规范中为路径定义该动词。 |
响应消息正文 |
|
示例
以下示例展示了使用 OASValidation 政策根据 OpenAPI 3.0 规范验证消息的一些方式。
验证请求消息
在以下示例中,myoaspolicy
政策根据 my-spec.json
OpenAPI 规范中定义的操作的请求消息正文架构来验证请求消息的正文。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.json</OASResource> <Options> <ValidateMessageBody>true</ValidateMessageBody> </Options> <Source>request</Source> </OASValidation>
如果消息正文不符合 OpenAPI 规范,则会返回 policies.oasvalidation.Failed
错误。
验证参数
下面的示例将政策配置为在请求中指定的标头、查询或 Cookie 参数未在 OpenAPI 规范中定义时失败。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<OASValidation>
元素
定义 OpenAPI 规范验证政策。
默认值 | 请参阅下面的默认政策标签页 |
是否必需? | 必填 |
类型 | 复杂对象 |
父元素 | 不适用 |
子元素 |
<DisplayName> <OASResource> <Source> <Options> <Source> |
语法
<OASValidation>
元素使用以下语法:
<OASValidation continueOnError="[true|false]" enabled="[true|false]" name="policy_name" > <!-- All OASValidation child elements are optional except OASResource --> <DisplayName>policy_display_name</DisplayName> <OASResource>validation_JSON_or_YAML</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> <Source>message_to_validate</Source> </OASValidation>
默认政策
以下示例显示了在 Apigee 界面中向您的流添加 OAS 验证政策时的默认设置:
<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1"> <DisplayName>OpenAPI Spec Validation-1</DisplayName> <Properties/> <Source>request</Source> <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource> </OASValidation>
此元素具有所有政策中常见的以下属性:
属性 | 默认 | 是否必需? | 说明 |
---|---|---|---|
name |
N/A | 必需 |
政策的内部名称。 (可选)使用 |
continueOnError |
false | 可选 | 设置为“false” 可在政策失败时返回错误。这是大多数政策的预期行为。如果设置为“true”,则即使政策失败,仍可继续执行流。 |
enabled |
是 | 可选 | 设为“true”可强制执行政策。设为“false”可“关闭”政策。即使政策仍附加到某个流,也不会强制执行该政策。 |
async |
false | 已弃用 | 此属性已弃用。 |
子元素参考
本部分介绍 <OASValidation>
的子元素。
<DisplayName>
除了用于 name
属性之外,还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。
<DisplayName>
元素适用于所有政策。
默认值 | 不适用 |
是否必需? | 可选。如果省略 <DisplayName> ,则会使用政策的 name 属性的值 |
Type | 字符串 |
父元素 | <PolicyElement> |
子元素 | 无 |
<DisplayName>
元素使用以下语法:
语法
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
示例
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
<DisplayName>
元素没有属性或子元素。
<OASResource>
指定验证依据的 OpenAPI 规范。您可以将此文件存储在以下位置:
- API 代理软件包中
/apiproxy/resources/oas
下的 API 代理范围 - API 代理编辑器的导航工具视图的
Resources
部分。
如需了解详情,请参阅管理资源。
您可以使用消息模板(如 {oas.resource.url}
)指定 OpenAPI 规范。在此示例中,流变量 oas.resource.url
(位于大括号中)的值将在运行时进行评估并替换为载荷字符串。如需了解详情,请参阅消息模板。
默认值 | 无 |
是否必需? | 必填 |
类型 | 字符串 |
父元素 |
<OASValidation>
|
子元素 | 无 |
语法
<OASResource>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> ... </OASValidation>
示例
以下示例引用了存储在 API 代理软件包中的 /apiproxy/resources/oas
下的 my-spec.yaml
规范:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> </OASValidation>
<OASResource>
元素没有特性或子元素。
<选项>
配置政策的选项。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 复杂类型 |
父元素 |
<OASValidation>
|
子元素 |
<ValidateMessageBody> <AllowUnspecifiedParameters> |
语法
<Options>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
示例
以下示例配置政策的选项。下文对各个选项进行了详细说明。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <ValidateMessageBody>false</ValidateMessageBody> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<ValidateMessageBody>
指定此政策是否应根据 OpenAPI 规范中操作的请求正文架构验证消息正文。设置为 true 则验证消息正文内容。设置为 false 则仅验证消息正文是否存在。
您可以将 <OASValidation>
元素的 continueOnError
特性设置为 true,以控制是否在发生验证错误后继续流执行。
默认值 | false |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Options>
|
子元素 | 无 |
语法
<ValidateMessageBody>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <ValidateMessageBody>[true|false]</ValidateMessageBody> </Options> ... </OASValidation>
示例
下例启用了对消息正文内容的验证:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <ValidateMessageBody>true</ValidateMessageBody> </Options> </OASValidation>
<AllowUnspecifiedParameters>
如果请求中存在 OpenAPI 规范中未定义的标头、查询或 Cookie 参数,请配置政策的行为。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 复杂类型 |
父元素 |
<Options>
|
子元素 |
<Header> <Query> <Cookie> |
语法
<AllowUnspecifiedParameters>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Header>[true|false]</Header> <Query>[true|false]</Query> <Cookie>[true|false]</Cookie> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
示例
下面的示例将政策配置为在请求中指定的标头、查询或 Cookie 参数未在 OpenAPI 规范中定义时失败。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> <Query>false</Query> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Header>
(<AllowUnspecifiedParameters>
的子元素)
如果请求中存在 OpenAPI 规范中未定义的标头参数,请配置政策的行为。
如需允许在请求中指定 OpenAPI 规范中未定义的标头参数,请将此参数设置为 true。否则,请将此参数设置为 false 以使政策执行失败。
默认值 | true |
是否必需? | 布尔值 |
类型 | 复杂类型 |
父元素 |
<AllowUnspecifiedParameters>
|
子元素 | 无 |
语法
<Header>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Header>[true|false]</Header> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
示例
以下示例将政策配置为在请求中指定了 OpenAPI 规范中未定义的标头参数时失败。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Query>
(<AllowUnspecifiedParameters>
的子元素)
如果请求中存在 OpenAPI 规范中未定义的查询参数,请配置政策的行为。
如需允许在请求中指定 OpenAPI 规范中未定义的查询参数,请将此参数设置为 true。否则,请将此参数设置为 false 以使政策执行失败。
默认值 | true |
是否必需? | 布尔值 |
类型 | 复杂类型 |
父元素 |
<AllowUnspecifiedParameters>
|
子元素 | 无 |
语法
<Query>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Query>[true|false]</Query> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
示例
以下示例将政策配置为在请求中指定了 OpenAPI 规范中未定义的查询参数时失败。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Query>false</Query> </AllowUnspecifiedParameters> </Options> </OASValidation>
如果请求中存在 OpenAPI 规范中未定义的 Cookie 参数,请配置政策的行为。
如要允许在未在 OpenAPI 规范中定义的请求中指定 Cookie 参数,请将此参数设置为 true。否则,请将此参数设置为 false 以使政策执行失败。
默认值 | true |
是否必需? | 布尔值 |
类型 | 复杂类型 |
父元素 |
<AllowUnspecifiedParameters>
|
子元素 | 无 |
语法
<Cookie>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Options> <AllowUnspecifiedParameters> <Query>[true|false]</Query> </AllowUnspecifiedParameters> </Options> ... </OASValidation>
示例
以下示例将政策配置为在请求中指定了 OpenAPI 规范中未定义的查询参数时失败。
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Cookie>false</Cookie> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Source>
根据 JSON 载荷攻击评估的 JSON 消息。通常将其设置为 request
,因为您通常需要评估来自客户端应用的入站请求。设置为 response 则评估响应消息。设置为 message 则在政策附加到请求流时自动评估请求消息,以及在政策附加到响应流时自动评估响应消息。
默认值 | request |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<Source>
|
子元素 | 无 |
语法
<Source>
元素使用以下语法:
<OASValidation name="policy_name"> <OASResource>oas://specname[.json|.yaml|.yml]</OASResource> <Source>[message|request|response]</Source> ... </OASValidation>
示例
以下示例在政策附加到请求流时自动评估请求消息,以及在政策附加到响应流时自动评估响应消息:
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Source>message</Source> </OASValidation>
<Source>
元素没有特性或子元素。
架构
每种政策类型均由 XML 架构 (.xsd
) 定义。GitHub 提供了政策架构作为参考。
错误代码
本部分介绍了在此政策触发错误时返回的错误代码和错误消息,以及 Edge 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
故障代码 | HTTP 状态 | 原因 | |
---|---|---|---|
steps.oasvalidation.Failed |
500 | 无法根据提供的 OpenAPI 规范验证请求消息正文。 | |
steps.oasvalidation.SourceMessageNotAvailable |
500 |
在政策的 |
|
steps.oasvalidation.NotMessageVariable |
500 |
|
build |
部署错误
在您部署包含此政策的代理时,可能会发生这些错误。
错误名称 | 原因 | |
---|---|---|
ResourceDoesNotExist |
<OASResource> 元素中引用的 OpenAPI 规范不存在。 |
|
ResourceCompileFailed |
部署中包含的 OpenAPI 规范包含会阻止其编译的错误。此错误通常表示该规范不是格式正确的 OpenAPI 规范 3.0。 | |
BadResourceURL |
无法处理 <OASResource> 元素中引用的 OpenAPI 规范。如果文件不是 JSON 或 YAML 文件,或未正确指定文件网址,则会发生这种情况。 |
故障变量
当此政策在运行时触发错误时,将设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
变量 | 其中 | 示例 |
---|---|---|
fault.name="fault_name" |
fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "ResourceDoesNotExist" |
oasvalidation.policy_name.failed |
policy_name 是抛出故障的政策的用户指定名称。 | oasvalidation.myoaspolicy.failed = true |
支持的 OpenAPI 规范特性
下表总结了 OASValidation 政策支持的 OpenAPI 规范特性,按类别划分。该表中也列出了不支持的特性。
类别 | 支持 | 不支持 |
---|---|---|
数据类型格式 | boolean date date-time double float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid |
binary byte password |
判别器对象 | mapping propertyName |
不适用 |
媒体类型对象 | schema | encoding example examples |
操作对象 | parameters requestBody responses security(部分支持) |
callbacks deprecated servers |
参数对象 | allowEmptyValue in ( query , header , path )required responses schema style ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )注意: deepObject 仅支持字符串参数,不支持数组和嵌套对象。 |
allowReserved deprecated example examples content |
路径对象 | delete get head options parameters patch post put trace variables |
移动后端代码 |
请求正文对象 | application/json application/hal+json application/x-www-form-urlencoded(不支持 encoding 对象)content required |
application/xml multipart/form-data text/plain text/xml |
响应对象 | application/json application/hal+json application/x-www-form-urlencoded(不支持 encoding 对象)content headers |
application/xml links text/plain text/xml |
响应对象 | default HTTP Status Code |
不适用 |
架构对象 | $ref additionalProperties (boolean flag variant only) allOf (ignored if additionalProperties is false )anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems |
deprecated example readOnly writeOnly xml |
安全机制对象 | in (header , query )(如果 type 为 http 则忽略)name type ( apiKey , http )
|
bearerFormat flows openIdConnectUrl scheme |
服务器对象 | url variables |
多个服务器定义 |