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>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

子元素参考

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

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<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 提供了政策架构作为参考。

错误代码

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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 500 Request 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.NotMessageVariable 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.

Variables Where Example
fault.name="fault_name" fault_name is 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"
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 		多个服务器定义

相关主题