OASValidation 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

關於 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 規格中路徑的動詞是否已定義。
要求訊息主體
  • 驗證要求中是否有訊息內文 (如有必要)。
  • 可視需要根據 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 規格驗證政策。

預設值 請參閱下方的「預設政策」分頁
是否必要？ 必填
類型 複雜物件
上層元素 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>

這個元素包含下列所有政策都適用的屬性：

屬性 預設 是否必要？ 說明
name 不適用 必要

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

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
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 代理程式編輯器的導覽器檢視畫面的 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 參數，則可設定政策的行為。

預設值 不適用
是否必要？ 選用
類型 複雜類型
上層元素 <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，以便導致政策執行失敗。

預設值 是
是否必要？ 布林值
類型 複雜類型
上層元素 <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 查看政策架構。

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

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

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

<Source> 元素設為非 message 類型的變數。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

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

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

變數 說明 範例
fault.category 錯誤類別。當政策拒絕要求時，這項值一律會保留 Step。 fault.category = "Step"
fault.name 錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "ResourceDoesNotExist"
fault.reason 錯誤的原因。這是使用者容易理解的字串，用來說明錯誤原因。 OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory 錯誤的子類別。當政策拒絕要求時，這項值一律會保留 OASValidationFailure。 fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 OASValidation.myoaspolicy.failed = true

支援的 OpenAPI 規範功能

OASValidation 政策支援 OpenAPI 規範功能，下表依類別列出這些功能。系統也會列出不支援的功能。

類別 支援 不支援
資料類型格式 boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 binary
byte
password
鑑別器物件 mapping
propertyName 		不適用
媒體類型物件 架構 編碼
範例
範例
作業物件 參數
requestBody
responses
安全性 (部分支援) 		回呼
已淘汰
伺服器
參數物件 allowEmptyValue
in (query, header, path)
required
responses
schema
style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

注意： deepObject 只支援字串參數，不支援陣列和巢狀物件。		 allowReserved
已淘汰
example
examples
內容
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
變數 		多個伺服器定義

在結構定義中使用模式

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 參數應符合指定的規則運算式，該運算式規定了 3 個字詞字元、一個破折號和 4 個小數字元的序列。

OpenAPI 規格會延遲 JSON 結構定義驗證標準，以便正式定義驗證字串值時的模式行為，並參考 JSON 結構定義核心標準，為結構定義作者提供關於受限規則運算式語法的建議。後者標準建議避免在 OpenAPI 規格文件的模式中使用 lookarounds (lookaheads 和 lookbehinds)、後向參照和八進制字元運算式等其他功能。

根據預設，Apigee 會驗證 OASValidation 政策參照的 OpenAPI 規格文件，並在規格文件格式不正確時回報錯誤。Apigee 也會驗證規格文件中的規則運算式，並回報發現的問題。

請務必注意，如果您使用的是建議子集以外的規則運算式功能，Apigee 不會驗證規則運算式，並會暫停對 OpenAPI 規範文件進行任何額外驗證。如果文件或規則運算式中使用了不在建議子集內的功能，或是 Apigee 執行階段不支援規則運算式功能，則只有在政策執行時才會在執行階段偵測到錯誤。

下表列出一些範例。

模式 行為
^\w{3}-\d{4}$

圖案有效。只使用建議子集內的正規表示式功能。Apigee 會允許儲存或匯入 Proxy，在執行階段，OASValidation 政策會正常運作，根據模式驗證參數。
^([a-z]\w{3}-\d{4}$

模式無效，因為缺少右括號。此模式不會使用建議子集以外的規則運算式功能。Apigee 會在您匯入或儲存 API Proxy 時回報這項錯誤。
^(?![a-z]\w{3}-\d{4}$

模式無效。與前一個範例一樣，這裡缺少右括號。不過，Apigee 不會在您儲存或匯入 API Proxy 時回報這項錯誤，因為正則運算式使用的是負向前瞻，而這項功能不在建議的正則運算式功能子集內。只有在政策執行時，系統才會在執行階段偵測到錯誤。
^(?![a-z])\w{3}-\d{4}$

模式是有效的，但使用了負向前瞻，而這項功能不在建議的正規表示式功能子集內。Apigee 會暫停驗證 OpenAPI 規範文件。在執行階段，當您執行參照使用此模式的規格 OASValidation 政策時，由於 Apigee 執行階段實際上支援負向前瞻，因此 Apigee 會正確套用此正規表示式來驗證參數值。
^(a)?b(?(1)c|d)$

模式有效，但使用擷取群組條件，而這項條件不在建議的正規表示式功能子集內。Apigee 會暫停驗證 OpenAPI 規範文件。在執行階段，如果您執行使用此模式參照規格的 OASValidation 政策，由於 Apigee 執行階段不支援此正規表示式功能，Apigee 會傳回錯誤。

建議您只在規則運算式中使用建議的子集功能，以免發生執行階段錯誤。

相關主題