OASValidation 政策

<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 规范中为路径定义该动词。
请求消息正文
  • 验证请求中是否存在消息正文（如果需要）。
  • （可选）根据 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 字符串
父元素 &lt;PolicyElement&gt;
子元素 无

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

如果请求中存在 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 		多个服务器定义

相关主题