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 代理软件包，如管理资源中所述。

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

注意：您只能使用 API 代理修订版本存储 OpenAPI 规范。请参阅资源存储位置。

验证哪些内容？

下表总结了 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	无	必需	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError	否	可选	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障
enabled	true	可选	设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async	否	已弃用	此属性已弃用。

子元素参考

本部分介绍 <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>

<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>

<Cookie>（<AllowUnspecifiedParameters> 的子元素）

如果请求中存在 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 提供了政策架构作为参考。

错误代码

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因
steps.oasvalidation.Failed	400	无法根据提供的 OpenAPI 规范验证请求消息正文。
steps.oasvalidation.Failed	500	无法根据提供的 OpenAPI 规范验证响应消息正文。
steps.oasvalidation.SourceMessageNotAvailable	500	在政策的 <Source> 元素中指定的变量超出范围或无法解析。
steps.oasvalidation.NonMessageVariable	500	<Source> 元素设置为非消息类型的变量。

部署错误

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

错误名称	原因
ResourceDoesNotExist	<OASResource> 元素中引用的 OpenAPI 规范不存在。
ResourceCompileFailed	部署中包含的 OpenAPI 规范包含会阻止其编译的错误。此错误通常表示该规范不是格式正确的 OpenAPI 规范 3.0。
BadResourceURL	无法处理 <OASResource> 元素中引用的 OpenAPI 规范。如果文件不是 JSON 或 YAML 文件，或未正确指定文件网址，则会发生这种情况。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	说明	示例
fault.category	故障的类别。如果政策拒绝请求，此变量将始终保持 Step。	fault.category = "Step"
fault.name	故障的名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	fault.name Matches "ResourceDoesNotExist"
fault.reason	故障的原因。它是人类可读的字符串，说明错误的原因。	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	故障的子类别。如果政策拒绝请求，此字段将始终保留 OASValidationFailure。	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name 是抛出故障的政策的用户指定名称。	OASValidation.myoaspolicy.failed = true

支持的 OpenAPI 规范特性

下表总结了 OASValidation 政策支持的 OpenAPI 规范特性，按类别划分。该表中也列出了不支持的特性。

注意：OASValidation 政策将拒绝使用不受支持的特性的 OpenAPI 规范。在这种情况下，该政策不会通过不受支持的特性的验证，并且 API 代理的部署将失败。

类别	支持	不支持
数据类型格式	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 运行时不支持此正则表达式功能。

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

相关主题

• JSON 威胁防范政策
• SOAPMessageValidation 政策