OASValidation 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

關於 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 政策透過元件驗證的要求訊息內容。

元件 提出驗證要求
基本路徑 驗證 API Proxy 定義的基本路徑。忽略 OpenAPI 規格中指定的 basepath。
路徑 驗證要求路徑 (減去 basepath) 符合 OpenAPI 規格定義的其中一個路徑模式。
動詞 驗證 OpenAPI 規格中的路徑是否已定義動詞。
要求訊息內文
  • 驗證要求中是否存在訊息內文 (如有需要)。
  • 您可以選擇根據 OpenAPI 規格中的作業要求主體結構定義驗證訊息內文。 使用 <ValidateMessageBody> 設定這個選項

注意：只有當 Content-Type 設為 application/json。如果內容類型未設定為 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 規格驗證政策。

預設值 請參閱下方的「預設政策」分頁。
是否必填？ 必填
類型 複雜物件
父項元素 不適用
子元素 <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>

預設政策

以下範例顯示新增 OAS 驗證政策時的預設設定 加入至 Apigee UI 的流程：

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

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然名稱。

<DisplayName> 元素適用於所有政策。

預設值 不適用
是否必填？ 選用設定。如果您省略 <DisplayName>， 使用政策的 name 屬性
類型 字串
父項元素 &lt;PolicyElement&gt;
子元素 無

<DisplayName> 元素使用下列語法：

語法

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

範例

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

<DisplayName> 元素不含任何屬性或子元素。

<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 Proxy 組合中 /apiproxy/resources/oas 下的 my-spec.yaml 規格：

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

<OASResource> 元素不含任何屬性或子元素。

&lt;Options&gt;

設定政策的選項。

預設值 不適用
是否必填？ 選用
類型 複雜類型
父項元素 <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>

&lt;ValidateMessageBody&gt;

指定政策是否應根據 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>

設定政策行為時，如果含有標頭、查詢或 Cookie 參數 中並未在 OpenAPI 規格中定義的要求。

預設值 不適用
是否必填？ 選用
類型 複雜類型
父項元素 <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>

設定政策行為 (有 Cookie 參數時) 中並未在 OpenAPI 規格中定義的要求。

若要允許在未於 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 提供許多資源。

錯誤代碼

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因
steps.oasvalidation.Failed 500 無法依據所提供的 OpenAPI 規格驗證要求訊息主體。
steps.oasvalidation.SourceMessageNotAvailable 500

你在政策的 <Source> 元素中指定的變數超出範圍，或是無法解析。
steps.oasvalidation.NotMessageVariable 500

<Source> 元素設定為不屬於 message 類型的變數。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤名稱 原因
ResourceDoesNotExist <OASResource> 元素中參照的 OpenAPI 規格不存在。
ResourceCompileFailed 部署作業中包含的 OpenAPI 規格含有導致無法編譯的錯誤。這通常表示規格並非格式正確的 OpenAPI 規格 3.0。
BadResourceURL 無法處理 <OASResource> 元素中參照的 OpenAPI 規格。如果檔案並非 JSON 或 YAML 檔案，或是檔案網址未正確指定，就會發生這種情況。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統會設定這些變數。詳情請參閱「政策錯誤須知」。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱，如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 oasvalidation.myoaspolicy.failed = true

支援的 OpenAPI 規格功能

OASValidation 政策支援 OpenAPI 規格功能，下表依類別概述。其中也會列出不支援的功能。

類別 有權限 不支援
資料類型格式 布林值
日期
日期時間
雙精準數
電子郵件
浮點值
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
字串
URI
uri-template
uuid
 二進位
位元組
密碼
鑑別器物件 對應
propertyName 		不適用
媒體類型物件 結構定義 編碼
範例
例子
作業物件 參數
requestBody
回應
安全 (部分支援) 		回呼
已淘汰
伺服器
參數物件 allowEmptyValue
攝於 (query、header、path)
必要
回應
結構定義
樣式 (deepObject、form、formmatrix、label、pipeDelimited、simple、spaceDelimited)

注意： deepObject 僅支援字串參數；不支援陣列和巢狀物件 		allowReserved
已淘汰
範例
示例
內容
路徑物件 刪除
取得
頭
選項
參數
修補程式
貼文
放置
追蹤記錄
變數 		伺服器
要求主體物件 application/json
application/hal+json
應用程式/x-www-form-urlencoded (不支援 encoding 物件)
內容
必選 		應用程式/xml
multipart/form-data
文字/純文字
文字/xml
回應物件 application/json
application/hal+json
應用程式/x-www-form-urlencoded (不支援 encoding 物件)
內容
標題 		應用程式/xml
連結
文字/純文字
文字/xml
回應物件 預設
HTTP 狀態碼 		不適用
結構定義物件 $ref
otherProperties (僅限布林標記子類)
allOf (additionalProperties 為 false 時忽略)
anyOf
列舉
exclusiveMaximum/exclusiveMinimum
格式
項目
最高/最低
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
不是
可為空值
oneOf
圖案
資源
必要
名稱
類型
uniqueItems 		已淘汰
範例
readOnly
writeOnly
XML
安全性配置物件 位於 (header，query) (如果 type 是 http 則忽略此值)
名稱
類型 (apiKey、http) 		bearerFormat
流量
openIdConnectUrl
配置
伺服器物件 url
變數 		多個伺服器定義

相關主題