OASValidation 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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>` 配置此选项

注意：Apigee 的 OASValidation 政策会以不同的方式验证请求和响应路径。
对于请求验证，它会验证 API 代理的请求路径（例如，https://<BasePath>/hello 的 /hello）。
对于响应验证，它会验证 Apigee 调用的目标端点的路径（例如，https://{target-basepath}}/apigee/hello 的 /apigee/hello）。
如果您的代理路径和目标路径不同，则必须了解这种区别，因为您必须相应地调整 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`	不适用	必需	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`continueOnError`	false	可选	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障
`enabled`	true	可选	设置为 `true` 可实施政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	false	已弃用	此属性已弃用。

子元素参考

本部分介绍 <OASValidation> 的子元素。

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 `<DisplayName>`，则会使用政策的 `name` 属性的值
类型	字符串
父元素	<`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 政策指定 <OASResource> 并将安全要求设置为全球级别，则系统不会强制执行安全要求。如需确保强制执行，必须在传入此政策的 <OASResource> 元素的 OpenAPI 规范中将所有安全要求设置为操作级别。如需了解详情，请参阅 Apigee 已知问题。

<选项>

配置政策的选项。

默认值	不适用
是否必需？	可选
类型	复杂类型
父元素	`<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 提供了政策架构作为参考。

错误代码

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.oasvalidation.Failed`	`400`	The Request message body cannot be validated against the provided OpenAPI Specification.
`steps.oasvalidation.Failed`	`500`	The Response message body cannot be validated against the provided OpenAPI Specification.
`steps.oasvalidation.SourceMessageNotAvailable`	`500`	Variable specified in the `<Source>` element of the policy is either out of scope or cannot be resolved.
`steps.oasvalidation.NonMessageVariable`	`500`	`<Source>` element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`ResourceDoesNotExist`	OpenAPI Specification referenced in the `<OASResource>` element does not exist.
`ResourceCompileFailed`	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
`BadResourceURL`	OpenAPI Specification referenced in the `<OASResource>` element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variable	Description	Example
`fault.category`	The category of the fault. When the policy rejects a request, this will always hold `Step`.	`fault.category = "Step"`
`fault.name`	The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ResourceDoesNotExist"`
`fault.reason`	The reason for the fault. It is a human-readable string explaining the reason for the fault.	`OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"`
`fault.subcategory`	The subcategory of the fault. When the policy rejects a request, this will always hold `OASValidationFailure`.	`fault.subcategory = "OASValidationFailure"`
`OASValidation.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`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	多个服务器定义

在架构中使用模式

OpenAPI 规范标准允许规范规定一个 schema 来描述参数或字段的数据类型。对于字符串类型的参数或字段，架构还可以定义 pattern，这是一个用来定义字符串的有效形式的正则表达式 (regex)。

例如，可以参考下面的 OpenAPI 规范片段：

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

此规范要求对于 getProduct 操作，product-id 参数应符合指定的正则表达式模式，即应为由 3 个字词字符、一个短划线和 4 个十进制数字构成的序列。

OpenAPI 规范遵循 JSON 架构验证标准来正式定义模式在验证字符串值时的行为，并遵循 JSON 架构核心标准来向架构作者推荐部分正则表达式语法。后一种标准建议应避免在 OpenAPI 规范文档内的模式中使用遍历（向前查找和向后查找）、反向引用和八进制字符表达式等特性。

默认情况下，Apigee 会验证 OASValidation 政策引用的 OpenAPI 规范文档，如果规范文档格式不正确，则会报告错误。Apigee 还会验证规范文档中的正则表达式模式，并报告发现的问题。

请务必注意，如果您使用推荐的子集之外的正则表达式功能，Apigee 将不会验证正则表达式，并将暂停 OpenAPI 规范文档的任何其他验证。如果文档或使用了推荐子集之外的功能的正则表达式中有错误，或者 Apigee 运行时不支持正则表达式功能，则只有在政策执行时，系统才会在运行时检测到错误。

下表提供了一些示例。

模式	行为
`^\w{3}-\d{4}$`	模式有效。它只使用了推荐子集中的正则表达式功能。Apigee 将允许保存或导入代理，并且在运行时，OASValidation 政策将按预期根据模式验证参数。
`^([a-z]\w{3}-\d{4}$`	模式无效；缺少右括号。模式未使用推荐子集之外的正则表达式功能。Apigee 会在您导入或保存 API 代理时报告此错误。
`^(?![a-z]\w{3}-\d{4}$`	模式无效。与前面的示例一样，它缺少右括号。但是，Apigee 在您保存或导入 API 代理时不会报告此错误，因为正则表达式使用了负向先行，这是推荐的正则表达式功能子集之外的功能。只有在政策执行时，系统才会在运行时检测到该错误。
`^(?![a-z])\w{3}-\d{4}$`	模式有效，但它使用了负向先行，这是推荐的正则表达式功能子集之外的功能。Apigee 将暂停 OpenAPI 规范文档验证。在运行时，当您执行引用使用此模式的规范的 OASValidation 政策时，Apigee 将正确应用此正则表达式来验证参数值，因为 Apigee 运行时实际上支持负向先行。
`^(a)?b(?(1)c\|d)$`	模式有效，但使用了捕获组条件，这是推荐的正则表达式功能子集之外的功能。Apigee 将暂停 OpenAPI 规范文档验证。在运行时，当您执行引用使用此模式的规范的 OASValidation 政策时，Apigee 将返回错误，因为 Apigee 运行时不支持此正则表达式功能。

我们建议您仅在正则表达式中使用推荐的功能子集，以防止运行时失败。

OASValidation 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

OASValidation 政策简介

验证哪些内容？

示例

验证请求消息

验证参数

<OASValidation> 元素

语法

默认政策

子元素参考

<DisplayName>

语法

示例

<OASResource>

语法

示例

<选项>

语法

示例

<ValidateMessageBody>

语法

示例

<AllowUnspecifiedParameters>

语法

示例

语法

示例

语法

示例

语法

示例

<Source>

语法

示例

此政策的架构

错误代码

Runtime errors

Deployment errors

Fault variables

支持的 OpenAPI 规范特性

在架构中使用模式

相关主题

OASValidation 政策

`<OASValidation>` 元素

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`