驗證內容

發行項
03/28/2024

適用於：所有 API 管理層

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

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

格式	內容類型
JSON	例如：`application/json` `application/hal+json`
XML	範例: `application/xml`
SOAP	允許的值：適用於 SOAP 1.2 API 的 `application/soap+xml` 適用於 SOAP 1.1 API 的 `text/xml`

注意

此驗證原則可使用的 API 結構描述大小上限為 4 MB。如果結構描述超過此限制，驗證原則會在執行階段傳回錯誤。若要增加大小限制，請連絡支援人員。

哪些內容經過驗證

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

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

提示

如需可用於結構描述的 Regex 模式限制式範例，請參閱 OWASP 驗證 Regex 存放庫。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。為了協助您設定此原則，入口網站會提供引導式表單型編輯器。深入了解如何設定或編輯 APIM 原則。

原則陳述式

<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" />
</validate-content>

屬性

屬性	描述	是必要欄位	預設
unspecified-content-type-action	未在 API 結構描述中指定之內容類型的要求或回應執行動作。允許使用原則運算式。	Yes	N/A
max-size	根據標頭 `Content-Length` 檢查的要求或回應主體長度上限，以位元組為單位。如果已壓縮要求本文或回應本文，此值就是解壓縮的長度。允許上限值：102,400 個位元組 (100 KB)。 (如果您需要提高此限制，請連絡支援服務。)允許使用原則運算式。	Yes	N/A
size-exceeded-action	根據主體超過 `max-size` 中指定的大小的要求或回應執行的動作。允許使用原則運算式。	Yes	N/A
errors-variable-name	要記錄驗證錯誤的 `context.Variables` 中變數名稱。不允許使用原則運算式。	No	N/A

元素

名稱	描述	必要
content-type-map	新增此元素，將傳入要求的內容類型或回應對應至另一個用來觸發驗證程序的內容類型。	No
content	新增一或多個此類元素，以驗證要求或回應中的內容類型，或對應的內容類型，並執行指定的動作。	No

content-type-map 屬性

屬性	描述	是必要欄位	預設
any-content-type-value	用於驗證要求或回應主體的內容類型 (不論傳入內容類型為何)。不允許使用原則運算式。	No	N/A
missing-content-type-value	用於驗證要求或回應主體的內容類型 (當傳入內容類型遺漏或空白)。不允許使用原則運算式。	No	N/A

content-type-map-elements

名稱	描述	必要
type	新增一或多個此類元素，將傳入內容類型對應至用來驗證要求或回應主體的內容類型。使用 `from` 來指定已知的傳入內容類型，或使用 `when` 搭配原則運算式來指定符合條件的任何傳入內容類型。如果已指定，則會覆寫 `any-content-type-value` 和 `missing-content-type-value` 中的對應。	No

內容屬性

屬性	描述	是必要欄位	預設
type	要執行本文驗證的內容類型，如有指定，則會根據內容類型標頭或對應的值在 `content-type-mapping` 中進行檢查。如為空白，其則會套用至 API 結構描述中指定的每個內容類型。若要驗證 SOAP 要求和回應 (`validate-as` 屬性設為 “soap”)，請為 SOAP 1.2 API 將 `type` 設為 `application/soap+xml`，或為 SOAP 1.1 API 設為 `text/xml`。	No	N/A
validate-as	驗證引擎，用於驗證具有相符 `type` 的要求或回應主體。支援的值：”json”、”xml”、”soap”。指定 “soap” 時，會從 SOAP 信封擷取來自要求或回應的 XML，並根據 XML 結構描述進行驗證。	Yes	N/A
schema-id	新增至 API 管理執行個體的現有結構描述名稱，用於內容驗證。如果未指定，則會使用 API 定義的預設結構描述。	No	N/A
schema-ref	針對 `schema-id` 中指定的 JSON 結構描述，JSON 文件中有效本機參考路徑的選擇性參考。範例：`#/components/schemas/address`。屬性應該會傳回 JSON 物件，API 管理處理為有效的 JSON 結構描述。對於 XML 結構描述，不支援 `schema-ref`，而且任何最上層結構描述元素都可以做為 XML 要求或回應承載的根目錄。驗證會檢查從 XML 要求或回應承載根目錄開始的所有元素都遵守提供的 XML 結構描述。	No	N/A
allow-additional-properties	布林值。針對 JSON 結構描述，指定是否實作結構描述中設定之 `additionalProperties` 值的執行階段覆寫： - `true`：允許要求或回應本文中的其他屬性，即使 JSON 結構描述的 `additionalProperties` 欄位設定為不允許其他屬性亦然。 - `false`：不允許要求或回應本文中的其他屬性，即使 JSON 結構描述的 `additionalProperties` 欄位設定為允許其他屬性亦然。若未指定屬性，原則將會根據結構描述中的 `additionalProperties` 欄位設定來驗證其他屬性。	No	N/A

動作

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

可以為 API 結構描述中表示的項目指定動作，並且根據原則，可以為 API 結構描述中未表示的項目指定動作。
原則子項目中指定的動作會覆寫為其父項目指定的動作。

可用動作：

動作	描述
略過	跳過驗證。
prevent	封鎖要求或回應處理、記錄詳細資訊驗證錯誤，並傳回錯誤。偵測到第一組錯誤時，就會中斷處理。
偵測	記錄驗證錯誤，而不會中斷要求或中斷回應處理。

使用方式

原則區段︰輸入、輸出、錯誤
原則範圍︰全域、工作區、產品、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 管理執行個體：

在入口網站中，瀏覽至您的 API 管理執行個體。
在左側功能表的 [API] 區段中，選取 [結構描述] > [+ 新增] 。
在 [建立結構描述] 視窗中，請執行下列動作：
1. 輸入結構描述的名稱 (識別碼)。
2. 在 [架構類型] 中，選取 [JSON] 或 [ XML] 。
3. 輸入說明。
4. 在 [建立方法] 中，執行下列其中一項：
  - 選取 [新建] ，然後輸入或貼上結構描述。
  - 選取 [從檔案匯入] 或 [從 URL 匯入] ，然後輸入結構描述位置。
    
    注意
    
    若要從 URL 匯入結構描述，必須能夠從瀏覽器透過網際網路存取該結構描述。
5. 選取 [儲存]。

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

注意

結構描述可能會交叉參考另一個新增至 API 管理執行個體的結構描述。例如，使用類似下列元素的元素，包含新增至 API 管理的 XML 結構描述：

<xs:include schemaLocation="/schemas/myschema" />

提示

開放原始碼工具可解析 WSDL 和 XSD 結構描述參考，以及將產生的結構描述批次匯入 GitHub 上的 API 管理。

範例

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]。

名稱	類型	驗證規則	詳細資料	公開回應	動作
validate-content
	RequestBody	SizeLimit	要求的本文長度為 {size} 個位元組，其超過 {maxSize} 個位元組的組態限制。	要求的本文長度為 {size} 個位元組，其超過 {maxSize} 個位元組的限制。	偵測/防止
	ResponseBody	SizeLimit	要求的本文長度為 {size} 個位元組，其超過 {maxSize} 個位元組的組態限制。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{messageContentType}	RequestBody	[未指定]	不允許未指定的內容類型 {messageContentType}。	不允許未指定的內容類型 {messageContentType}。	偵測/防止
{messageContentType}	ResponseBody	[未指定]	不允許未指定的內容類型 {messageContentType}。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	ApiSchema		API 的結構描述不存在或無法進行解析。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	ApiSchema		API 的結構描述未指定定義。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	API 的結構描述不包含與內容類型 {messageContentType} 相關聯的定義 {definitionName}。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{messageContentType}	RequestBody	IncorrectMessage	要求的本文不符合與內容類型 {messageContentType} 相關聯的定義 {definitionName}。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	要求的本文不符合與內容類型 {messageContentType} 相關聯的定義 {definitionName}。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	偵測/防止
{messageContentType}	ResponseBody	IncorrectMessage	回應的本文不符合與內容類型 {messageContentType} 相關聯的定義 {definitionName}。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	RequestBody	ValidationException	無法驗證內容類型 {messageContentType} 的要求本文。 {例外狀況詳細資料}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	ResponseBody	ValidationException	無法驗證內容類型 {messageContentType} 的回應本文。 {例外狀況詳細資料}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	[未指定]	不允許未指定的 {路徑參數/查詢參數/標頭} {paramName}。	不允許未指定的 {路徑參數/查詢參數/標頭} {paramName}。	偵測/防止
{headerName}	ResponseHeader	[未指定]	不允許未指定的標頭 {headerName} 。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	ApiSchema		API 的結構描述不存在或無法進行解析。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
	ApiSchema		API 結構描述未指定定義。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	API 的結構描述不包含定義 {definitionName}，與 {查詢參數/路徑參數/標頭} {paramName} 相關聯。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	要求不能包含 {查詢參數/路徑參數/標頭} {paramName} 的多個值。	要求不能包含 {查詢參數/路徑參數/標頭} {paramName} 的多個值。	偵測/防止
{headerName}	ResponseHeader	IncorrectMessage	回應不能包含標頭 {headerName} 的多個值。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	{查詢參數/路徑參數/標頭} {paramName} 的值不符合定義。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	{查詢參數/路徑參數/標頭} {paramName} 的值不符合定義。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	偵測/防止
{headerName}	ResponseHeader	IncorrectMessage	標頭 {headerName} 的值不符合定義。 {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	無法根據定義剖析 {查詢參數/路徑參數/標頭} {paramName} 的值。 {ex.Message}	無法根據定義剖析 {查詢參數/路徑參數/標頭} {paramName} 的值。 {ex.Message}	偵測/防止
{headerName}	ResponseHeader	IncorrectMessage	標頭 {headerName} 的值無法根據定義進行剖析。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{paramName}	QueryParameter / PathParameter / RequestHeader	ValidationError	無法驗證 {查詢參數/路徑參數/標頭}{paramName}。 {例外狀況詳細資料}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
{headerName}	ResponseHeader	ValidationError	無法驗證標頭 {headerName}。 {例外狀況詳細資料}	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止
validate-status-code
{status-code}	StatusCode	[未指定]	不允許回應狀態碼 {status-code}。	由於發生內部錯誤，所以無法處理要求。請連絡 API 擁有者。	偵測/防止

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

原因	訊息
錯誤要求	內容變數的 {細節}，用戶端的 {公開回應}
不允許回應	內容變數的 {細節}，用戶端的 {公開回應}

內容驗證

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