此页面由 Cloud Translation API 翻译。

OASValidation 政策

您正在查看 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 规范中为路径定义该动词。
请求消息正文	验证请求中是否存在消息正文（如果需要）。（可选）根据 OpenAPI 规范中操作的请求正文架构验证消息正文。使用 `<ValidateMessageBody>` 配置此选项注意：仅在 Content-Type 设置为 `application/json` 时，此政策才会根据 OpenAPI 规范验证请求消息正文。如果内容类型未设置为 `application/json`，则请求消息正文验证将自动通过（无需实际验证内容）。
参数	验证请求中是否存在必需参数，包括路径、标头、查询和 Cookie 参数。验证参数值是否与 OpenAPI 规范中定义的相应参数值相匹配。（可选）验证请求中是否存在 OpenAPI 规范中未定义的参数。使用 `<AllowUnspecifiedParameters>` 配置此选项

下表总结了 OASValidation 政策验证的响应消息内容，按组件划分。

组件	回复验证
路径	验证请求路径（去掉基本路径）是否与 OpenAPI 规范中定义的某一路径模式匹配。
动词	验证是否已在 OpenAPI 规范中为路径定义该动词。
响应消息正文	验证响应中是否存在消息正文（如果需要）。验证 OpenAPI 规范中的响应标头是否存在于响应消息中，以及响应标头的值是否与架构匹配。（可选）根据 OpenAPI 规范中的操作响应正文架构验证消息正文。使用 `<ValidateMessageBody>` 配置此选项

示例

以下示例展示了使用 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	必需	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`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，以控制是否在发生验证错误后继续流执行。

注意：仅在 Content-Type 设置为 application/json 时，此政策才会根据 OpenAPI 规范验证请求消息正文。如果内容类型未设置为 application/json，则请求正文消息验证将自动成功（无需实际验证内容）。

默认值	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>

如果请求中存在 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	在政策的 `<Source>` 元素中指定的变量超出范围或无法解析。
`steps.oasvalidation.NotMessageVariable`	500	`<Source>` 元素设置为非消息类型的变量。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	原因
`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 email 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	多个服务器定义

OASValidation 政策

OASValidation 政策简介

验证哪些内容？

示例

验证请求消息

验证参数

<OASValidation> 元素

语法

默认政策

子元素参考

<DisplayName>

语法

示例

<OASResource>

语法

示例

<选项>

语法

示例

<ValidateMessageBody>

语法

示例

<AllowUnspecifiedParameters>

语法

示例

语法

示例

语法

示例

语法

示例

<Source>

语法

示例

架构

错误代码

运行时错误

部署错误

故障变量

支持的 OpenAPI 规范特性

相关主题

`<OASValidation>` 元素

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`