本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
關於 OASValidation 政策
OASValidation (OpenAPI 規格驗證) 政策可讓您使用 JSON 或 YAML 格式,根據 OpenAPI 3.0 規格驗證傳入的要求或回應訊息。請參閱「驗證哪些內容?」一文。
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 規格中是否已為路徑定義動詞。 |
要求訊息主體 |
注意:只有在 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 規格驗證政策。
預設值 | 請參閱下方的「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>
這個元素包含下列所有政策都適用的屬性:
屬性 | 預設 | 是否必要? | 說明 |
---|---|---|---|
name |
不適用 | 必要 |
政策的內部名稱。 您可以選擇使用 |
continueOnError |
false | 選用 | 將其設為 false ,即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true ,即使政策失敗,流程執行作業仍會繼續進行。另請參閱:
|
enabled |
是 | 選用 | 設為 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 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>
<Header>
(<AllowUnspecifiedParameters>
的子項)
設定政策的行為,如果要求中存在 OpenAPI 規格未定義的標頭參數。
如要允許在要求中指定 OpenAPI 規格未定義的標頭參數,請將這個參數設為 true。否則,請將這個參數設為 false,導致政策執行失敗。
預設值 | 是 |
必填與否 | 布林值 |
類型 | 複雜型別 |
父項元素 |
<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,導致政策執行失敗。
預設值 | 是 |
必填與否 | 布林值 |
類型 | 複雜型別 |
父項元素 |
<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,導致政策執行失敗。
預設值 | 是 |
必填與否 | 布林值 |
類型 | 複雜型別 |
父項元素 |
<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 Apigee 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 |
400 |
The Request message body cannot be validated against the provided OpenAPI Specification. |
steps.oasvalidation.Failed |
500 |
The Response message body cannot be validated against the provided OpenAPI Specification. |
steps.oasvalidation.SourceMessageNotAvailable |
500 |
Variable specified in the |
steps.oasvalidation.NonMessageVariable |
500 |
|
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.
Variable | Description | Example |
---|---|---|
fault.category |
The category of the fault. When the policy rejects a request, this will always hold Step . |
fault.category = "Step" |
fault.name |
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" |
fault.reason |
The reason for the fault. It is a human-readable string explaining the reason for the fault. | OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]" |
fault.subcategory |
The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure . |
fault.subcategory = "OASValidationFailure" |
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 必要 |
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 |
伺服器物件 | 網址 變數 |
多個伺服器定義 |
在結構定義中使用模式
OpenAPI 規格標準允許規格規定 schema
,用來描述參數或欄位的資料類型。如果是字串類型的參數或欄位,結構定義也可以定義 pattern
,也就是定義字串有效格式的規則運算式。
舉例來說,請參考下列 OpenAPI 規格片段:
paths: /products/{product-id}: get: operationId: getProduct summary: Get product by id description: returns information regarding a product, by id parameters: - name: product-id in: path description: id of the product required: true schema: type: string pattern: '^\w{3}-\d{4}$'
這項規格規定,對於 getProduct
作業,product-id
參數應符合指定的 regex,其中規定 3 個字元、一個破折號和 4 個十進位數字的序列。
OpenAPI 規格會參照JSON 結構定義驗證標準,正式定義驗證字串值時的模式行為,並參照 JSON 結構定義核心標準,向結構定義作者提供有關受限正規運算式語法的建議。後者建議在 OpenAPI 規格文件的模式中,避免使用環顧 (lookahead 和 lookbehind)、反向參照和八進位字元運算式等功能。
根據預設,Apigee 會驗證 OASValidation 政策參照的 OpenAPI 規格文件,如果規格文件格式不正確,就會回報錯誤。Apigee 也會驗證規格文件中的正則運算式模式,並回報發現的問題。
請注意,如果您使用建議子集以外的 regex 功能,Apigee 將「不會」驗證 regex,並暫停對 OpenAPI 規格文件的任何額外驗證。如果文件或 regex 發生錯誤,或使用建議子集以外的功能,或 regex 功能不受 Apigee 執行階段支援,系統只會在政策執行時偵測到錯誤。
下表提供一些範例。
模式 | 行為 |
---|---|
^\w{3}-\d{4}$ |
圖案有效。它只會使用建議子集中的 regex 功能。 Apigee 允許儲存或匯入 Proxy,且在執行階段,OASValidation 政策會如預期運作,根據模式驗證參數。 |
^([a-z]\w{3}-\d{4}$ |
模式無效,缺少右括號。 模式不會使用建議子集以外的 regex 功能。 匯入或儲存 API Proxy 時,Apigee 會回報這項錯誤。 |
^(?![a-z]\w{3}-\d{4}$ |
模式無效。與先前的範例一樣,這個範例缺少右括號。 但 Apigee 不會在您儲存或匯入 API Proxy 時回報這項錯誤,因為該規則運算式使用負向先行斷言,這不屬於建議的規則運算式功能子集。只有在政策執行時,系統才會在執行階段偵測到錯誤。 |
^(?![a-z])\w{3}-\d{4}$ |
模式有效,但使用負向先行斷言,這不在建議的 regex 功能子集中。Apigee 會暫停驗證 OpenAPI 規格文件。在執行階段,當您執行使用此模式參照規格的 OASValidation 政策時,由於 Apigee 執行階段實際支援負向先行斷言,Apigee 會正確套用此正則運算式來驗證參數值。 |
^(a)?b(?(1)c|d)$ |
模式有效,但使用擷取群組條件,這不在建議的 regex 功能子集中。Apigee 會暫停驗證 OpenAPI 規格文件。在執行階段,當您執行 OASValidation 政策,並使用這個模式參照規格時,由於 Apigee 執行階段不支援這項正則運算式功能,Apigee 會傳回錯誤。 |
建議您只在 regex 中使用建議的子集功能,以免發生執行階段錯誤。