驗證內容

適用於：所有 APIM 層

validate-content 原則會根據一個或多個支援的 API 結構描述驗證要求或回應本文的大小或內容。

下表顯示原則支援的結構描述格式和要求或回應內容類型。 內容類型值不區分大小寫。

哪些內容經過驗證

此原則會根據結構描述驗證要求或回應中的下列內容：

• 所有必要屬性是否存在。
• 如果結構描述已設定 additionalProperties 欄位，是否有其他屬性存在。 可以使用 allow-additional-properties 屬性覆寫。
• 所有屬性的類型。 例如，如果結構描述將屬性指定為整數，則要求 (或回應) 必須包含整數，而不是另一種類型，例如字串。
• 如果在結構描述中指定屬性的格式，例如 RegEx (如果指定 pattern 關鍵字)，minimum 指定為整數等等。

原則陳述式

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

屬性

元素

content-type-map 屬性

content-type-map-elements

內容屬性

動作

內容驗證原則都包含一或多個指定動作的屬性，API 管理在根據 API 結構描述驗證 API 要求或回應中的實體時會採取此動作。

• 可以為 API 結構描述中表示的項目指定動作，並且根據原則，可以為 API 結構描述中未表示的項目指定動作。

• 原則子項目中指定的動作會覆寫為其父項目指定的動作。

可用動作：

使用方式

• 原則區段︰輸入、輸出、錯誤
• 原則範圍︰全域、工作區、產品、API、作業
• 閘道： 傳統、v2、使用量、自我裝載、工作區

記錄

原則執行期間驗證錯誤的詳細資料會記錄到原則根項目 errors-variable-name 屬性中指定的 context.Variables 變數。 在動作 prevent 中設定時，驗證錯誤會封鎖進一步的要求或回應處理，而且也會傳播至 context.LastError 屬性。

若要調查錯誤，請使用追蹤原則將內容變數的錯誤記錄到 Application Insights。

對於效能的影響

新增驗證原則可能會影響 API 輸送量。 下列為一般適用的原則：

• API 結構描述大小越大，輸送量就越低。
• 要求或回應中的承載越大，輸送量就越低。
• API 結構描述的大小會對效能造成的影響比承載大小造成的影響更大。
• 根據大小為數 MB 的 API 結構描述進行驗證，可能會導致某些情況下的要求或回應逾時。 在服務的取用和開發人員層級中，效果會更明顯。

建議您使用預期的生產工作負載執行負載測試，以評估驗證原則對 API 輸送量造成的影響。

內容驗證的結構描述

根據預設，要求或回應內容的驗證會使用來自 API 定義的 JSON 或 XML 結構描述。 將 API 從 OpenAPI 或 WSDL 規格匯入 API 管理時，可以手動指定或自動產生這些結構描述。

使用 validate-content 原則時，您可以選擇性地根據已新增至 API 管理執行個體且不屬於 API 定義的一或多個 JSON 或 XML 結構描述進行驗證。 您新增至 API 管理的結構描述可以跨許多 API 重複使用。

若要使用 Azure 入口網站，將結構描述新增至您的API 管理執行個體：

1. 在入口網站中，瀏覽至您的 API 管理執行個體。

2. 在左側功能表的 [API] 區段中，選取 [結構描述] > [+ 新增] 。

3. 在 [建立結構描述] 視窗中，請執行下列動作：

   1. 輸入結構描述的名稱 (識別碼)。
   2. 在 [架構類型] 中，選取 [JSON] 或 [ XML] 。
   3. 輸入說明。
   4. 在 [建立方法] 中，執行下列其中一項：
      • 選取 [新建] ，然後輸入或貼上結構描述。
      • 選取 [從檔案匯入] 或 [從 URL 匯入] ，然後輸入結構描述位置。

        注意

        若要從 URL 匯入結構描述，必須能夠從瀏覽器透過網際網路存取該結構描述。

   5. 選取 [儲存]。

   

API 管理會在相對 URI /schemas/<schemaId> 上新增結構描述資源，而該結構描述會出現在 [結構描述] 頁面上的清單。 選取結構描述以檢視其屬性，或在結構描述編輯器中加以編輯。

範例

JSON 結構描述驗證

在下列範例中，API 管理將具有空白內容類型標頭的要求或內容類型標頭 application/hal+json 的要求解譯為內容類型為 application/json 的要求。 然後，API 管理會根據 API 定義中 application/json 內容類型所定義的結構描述，在偵測模式中執行驗證。 承載大於 100 KB 的訊息會遭到封鎖。 即使結構描述的 additionalProperties 欄位設定為允許其他屬性，仍會封鎖包含其他屬性的要求。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

SOAP 結構描述驗證

在下列範例中，不論傳入內容類型為何，API 管理將任何要求解譯為內容類型 application/soap+xml (SOAP 1.2 API 所使用的內容類型) 的要求。 該要求可能會以空白的內容類型標頭、類型標頭 text/xml (由 SOAP 1.1 API 所使用) 或其他內容類型標頭。 然後，API 管理從 SOAP 信封擷取 XML 承載，並根據名為 “myschema” 的結構描述，以預防模式執行驗證。 承載大於 100 KB 的訊息會遭到封鎖。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

驗證錯誤

API 管理會產生下列格式的內容驗證錯誤：

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

下表列出驗證原則的所有可能錯誤。

• 詳細資料：可用於調查錯誤。 並非要公開共用。
• 公開回應：傳回給用戶端的錯誤。 不會洩漏實作詳細資料。

當驗證原則指定 prevent 動作並產生錯誤時，來自 API 管理的回應會包含 HTTP 狀態碼：在輸入區段中套用原則時為 [400]，當原則套用至輸出區段時為 [502]。

下表列出驗證錯誤的所有可能 Reason 值，以及可能的 Message 值：

相關原則

• 內容驗證

相關內容

如需使用原則的詳細資訊，請參閱：

• 教學課程：轉換及保護 API
• 原則參考，取得原則陳述式及其設定的完整清單
• 原則運算式
• 設定或編輯原則
• 重複使用原則設定
• 原則程式碼片段存放庫 (英文)
• Azure API 管理 原則工具組
• 使用 Microsoft Azure Copilot 撰寫原則