您正在查看 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 代理程式套件的資源,如「管理資源」一文所述。
哪些內容會經過驗證?
下表依元件分類,概述由 OASValidation 政策驗證的要求訊息內容。
元件 | 提出驗證要求 |
---|---|
Basepath | 驗證 API Proxy 定義的 basepath,忽略 OpenAPI 規格中指定的 basepath。 |
路徑 | 驗證要求路徑 (不含 basepath) 是否符合 OpenAPI 規格中定義的路徑模式。 |
動詞 | 驗證 OpenAPI 規格中路徑的動詞是否已定義。 |
要求訊息主體 |
注意:只有在 Content-Type 設為 |
參數 |
|
下表依元件分類,摘要列出 OASValidation 政策驗證的回應訊息內容。
元件 | 回應驗證 |
---|---|
路徑 | 驗證要求路徑 (不含 basepath) 是否符合 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
錯誤。
以下範例會將政策設為在要求中指定的標頭、查詢或 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 規格驗證政策。
預設值 | 請參閱下方的「預設政策」分頁 |
是否為必要欄位? | 必填 |
類型 | 複雜物件 |
上層元素 | n/a |
子元素 |
<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>
除了 name
屬性之外,您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱,為政策加上標籤。
<DisplayName>
元素適用於所有政策。
預設值 | 不適用 |
是否必要? | 選用設定。如果省略 <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 代理程式編輯器的導覽器檢視畫面的
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 參數,則可設定這項政策的行為。
<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>
<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>
如果要求中含有 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 查看政策架構。
錯誤代碼
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 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 |
二進位 位元組 密碼 |
鑑別器物件 | mapping propertyName |
不適用 |
媒體類型物件 | 架構 | 編碼 範例 範例 |
作業物件 | 參數 requestBody 回應 安全性 (部分支援) |
回呼 已淘汰 伺服器 |
參數物件 | allowEmptyValue in ( query , header , path )required responses schema style ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )注意: deepObject 僅支援字串參數,不支援陣列和巢狀物件。 |
allowReserved 已淘汰 示例 示例 內容 |
Paths 物件 | delete get head options parameters patch post put trace 變數 |
伺服器 |
要求主體物件 | application/json application/hal+json application/x-www-form-urlencoded ( encoding 物件不支援)content 必要 |
application/xml multipart/form-data text/plain text/xml |
回應物件 | application/json application/hal+json application/x-www-form-urlencoded ( encoding 物件不支援)內容 標頭 |
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 |
安全性配置文件物件 | in (header , query ) (如果 type 是 http ,則會忽略)name type ( apiKey , http )
|
bearerFormat flows openIdConnectUrl scheme |
伺服器物件 | url 變數 |
多個伺服器定義 |