OASValidation 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

關於 OASValidation 政策

您可以使用 OASValidation (OpenAPI 規格驗證) 政策，根據 OpenAPI 3.0 規格 (JSON 或 YAML) 驗證傳入的要求或回應訊息。 請參閱「驗證哪些內容？」一文。

OASValidation 政策會指定要用於驗證的 OpenAPI 規格名稱，政策附加的步驟執行時會進行驗證。 OpenAPI 規格會儲存在 API Proxy 套件的下列標準位置，做為資源：apiproxy/resources/oas。 OpenAPI 規格必須有 .json、.yml、.yaml 擴充功能。

使用 UI 或 API 將 OpenAPI 規格新增為 API Proxy 套件的資源，詳情請參閱「管理資源」。

系統會驗證哪些內容？

下表依元件列出 OASValidation 政策驗證的要求訊息內容摘要。

元件 提出驗證要求
Basepath 驗證 API Proxy 定義的 basepath，並忽略 OpenAPI 規格中指定的 basepath。
路徑 驗證要求路徑 (減去 basepath) 是否符合 OpenAPI 規格中定義的路徑模式。
動詞 驗證 OpenAPI 規格中是否已為路徑定義動詞。
要求訊息主體
  • 視需要驗證要求中是否有訊息內文。
  • (選用) 根據 OpenAPI 規格中的作業要求主體結構定義，驗證訊息主體。使用 <ValidateMessageBody> 設定這個選項。

注意：只有在 Content-Type 設為 application/json 時，這項政策才會根據 OpenAPI 規格驗證要求訊息主體。如果內容類型未設為 application/json，系統會自動通過要求訊息主體驗證 (但不會實際驗證內容)。
參數
  • 驗證要求中是否包含必要參數，包括路徑、標頭、查詢和 Cookie 參數。
  • 驗證參數值是否與 OpenAPI 規格中定義的值相符。
  • (選用) 驗證要求中是否有 OpenAPI 規格未定義的參數。使用 <AllowUnspecifiedParameters> 設定這個選項。

下表依元件摘要列出由 OASValidation 政策驗證的回應訊息內容。

元件 回應驗證
路徑 驗證要求路徑 (減去 basepath) 是否符合 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 規格驗證政策。

預設值 請參閱下方的「Default Policy」分頁
必填與否 必填
類型 複雜物件
父項元素 不適用
子元素 <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 UI 中將 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>

此元素在所有政策中皆包含下列屬性：

屬性 預設 必填與否 Description
name 無 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個字元。

或者，您也可以使用 <DisplayName> 元素，在管理 UI Proxy 編輯器中，以不同的自然語言名稱來標示政策。
continueOnError false 選填 如果設為「false」，當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」，則在政策失敗後，仍會繼續執行流程。
enabled true 選填 設為「true」即可強制執行政策。將政策設為「false」，即可「關閉」政策。即使政策已附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 這項屬性已淘汰。

子元素參照

本節說明 <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 Proxy 套件中 /apiproxy/resources/oas 下的 API Proxy 範圍
  • API Proxy 編輯器的「Navigator」檢視畫面 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> 元素沒有屬性或子項元素。

<Options>

設定政策的選項。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <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」，即可在政策附加至要求流程時自動評估要求訊息，以及在政策附加至回應流程時評估回應訊息。

預設值 申請。
必填與否 選用
類型 字串
父項元素 <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 規格功能，相關摘要說明請見下表 (依類別分類)。並列出不支援的功能。

類別 支援 不支援
資料類型格式 布林值
日期
日期時間
雙精度浮點數
電子郵件地址
浮點數
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
字串
URI
URI 範本
UUID
 binary
byte
password
鑑別器物件 mapping
propertyName 		不適用
媒體類型物件 結構定義 encoding
example
examples
作業物件 parameters
requestBody
responses
security (部分支援) 		回呼
已淘汰
伺服器
參數物件 allowEmptyValue
in (query, header, path)
required
responses
schema
style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

注意： deepObject 僅支援字串參數，不支援陣列和巢狀物件。 		allowReserved
deprecated
example
examples
content
Paths 物件 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
Responses 物件 default
HTTP 狀態碼 		不適用
結構定義物件 $ref
additionalProperties (僅限布林值標記變數)
allOf (如果 additionalProperties 是 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
安全配置物件 (header, query) (如果 type 為 http，則會忽略)
名稱
類型 (apiKey、http) 		bearerFormat
flows
openIdConnectUrl
scheme
伺服器物件 網址
變數 		多個伺服器定義

相關主題