您正在查看 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 規格中指定的基本路徑。 |
路徑 | 驗證要求路徑 (減去基本路徑) 是否符合 OpenAPI 規格中定義的其中一個路徑模式。 |
動詞 | 驗證動詞已定義於 OpenAPI 規格中的路徑。 |
要求訊息內文 |
注意:只有在 Content-Type 設為 |
參數 |
|
下表統整了 OASValidation 政策依元件驗證的回應訊息內容。
元件 | 回應驗證 |
---|---|
路徑 | 驗證要求路徑 (減去基本路徑) 是否符合 OpenAPI 規格中定義的其中一個路徑模式。 |
動詞 | 驗證動詞已定義於 OpenAPI 規格中的路徑。 |
回應訊息內文 |
|
範例
以下範例說明使用 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
錯誤。
驗證參數
以下範例將設定在 OpenAPI 規格中並未定義的要求中指定標頭、查詢或 Cookie 參數時,使政策失敗。
<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 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 |
無 | 必要 |
政策的內部名稱。 或者,您也可以使用 |
continueOnError |
false | 選填 | 如果設為「false」,當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」,則在政策失敗後,仍會繼續執行流程。 |
enabled |
true | 選填 | 設為「true」即可強制執行政策。將政策設為「false」,即可「關閉」政策。即使政策已附加至流程,系統也不會強制執行這項政策。 |
async |
false | 已淘汰 | 這項屬性已淘汰。 |
子元素參考資料
本節將說明 <OASValidation>
的子元素。
<DisplayName>
在管理 UI Proxy 編輯器中,除了 name
屬性,可用以其他自然更自然的名稱為政策加上標籤。
<DisplayName>
元素適用於所有政策。
預設值 | n/a |
是否必填? | 選用設定。如果省略 <DisplayName> ,則會使用政策的 name 屬性值 |
類型 | 字串 |
父項元素 | <PolicyElement> |
子元素 | 無 |
<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>
元素沒有屬性或子元素。
<選項>
設定政策選項。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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>
如果要求中出現標頭、查詢或 Cookie 參數,但未在 OpenAPI 規格中定義,這項政策會設定政策行為。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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>
範例
以下範例將設定在 OpenAPI 規格中並未定義的要求中指定標頭、查詢或 Cookie 參數時,使政策失敗。
<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 參數,但未在 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 |
你在政策的 |
|
steps.oasvalidation.NotMessageVariable |
500 |
|
build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | |
---|---|---|
ResourceDoesNotExist |
<OASResource> 元素中參照的 OpenAPI 規格不存在。 |
|
ResourceCompileFailed |
部署作業中包含的 OpenAPI 規格含有導致無法編譯的錯誤。這通常表示規格並非格式正確的 OpenAPI 規格 3.0。 | |
BadResourceURL |
無法處理 <OASResource> 元素中參照的 OpenAPI 規格。如果檔案並非 JSON 或 YAML 檔案,或是檔案網址未正確指定,就會發生這種情況。 |
錯誤變數
當這項政策在執行階段觸發錯誤時,系統會設定這些變數。詳情請參閱「政策錯誤須知」。
支援的 OpenAPI 規格功能
OASValidation 政策支援 OpenAPI 規格功能,各類別摘要如下表所列。下表中也會列出不支援的功能。
類別 | 有權限 | 無權限 |
---|---|---|
資料類型格式 | boolean date date-time double float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid |
二進位 位元組 密碼 |
鑑別器物件 | 對應 propertyName |
不適用 |
媒體類型物件 | 結構定義 | 如果您要 範例 範例 |
作業物件 | 參數 requestBody 回應 安全性 (部分支援) |
回呼 已淘汰 伺服器 |
參數物件 | (query 、header 、path )必須提供 回應 結構定義 樣式 ( deepObject 、form 、formmatrix 、label 、pipeDelimited 、simple 、spaceDelimited )注意: deepObject 僅支援字串參數;不支援陣列和巢狀物件。
|
allowReserved 已淘汰 範例 範例 內容 |
Paths 物件 | 刪除 get head options 參數 patch post put trace 變數 |
伺服器 |
要求主體物件 | application/json application/hal+json application/x-www-form-urlencoded (不支援 encoding 物件)內容 必要 |
application/xml multipart/form-data text/plain text/xml |
回應物件 | application/json application/hal+json application/x-www-form-urlencoded (不支援 encoding 物件)內容 標頭 |
application/xml 連結 text/plain text/xml |
回應物件 | 預設 HTTP 狀態碼 |
不適用 |
結構定義物件 | $ref additionalProperties (僅限布林旗標變化版本) allOf (如果 additionalProperties 為 false 時會忽略)anyOf 列舉 Exclusiveed/ExclusiveMinimum format items max/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf unique 模式 屬性 |
已淘汰 範例 readOnly writeOnly xml |
安全性配置物件 | 包含於 (header 、query ) (如果 type 為 http 則忽略)名稱 類型 ( apiKey , http ) |
bearerFormat flows openIdConnectUrl 配置 |
伺服器物件 | url 變數 |
多個伺服器定義 |