共用方式為

驗證標頭

  • 發行項

適用於：所有 APIM 層

validate-headers 原則會根據 API 結構描述驗證回應標頭。

重要

如果您使用管理 API 版本 2021-01-01-preview 之前的版本匯入 API，則 validate-headers 原則可能無法運作。 您可能需要使用管理 API 版本 2021-01-01-preview 或更新版本來重新匯入您的 API。

注意

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

注意

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

原則陳述式

<validate-headers specified-header-action="ignore | prevent | detect" unspecified-header-action="ignore | prevent | detect" errors-variable-name="variable name">
    <header name="header name" action="ignore | prevent | detect" />
</validate-headers>

屬性

屬性 描述 是必要欄位 預設
specified-header-action API 結構描述中指定的要求參數所需執行的動作。 允許使用原則運算式。 Yes N/A
unspecified-header-action API 結構描述中未指定的要求參數所需執行的動作。 允許使用原則運算式。 Yes N/A
errors-variable-name 要記錄驗證錯誤的 context.Variables 中變數名稱。 不允許使用原則運算式。 No N/A

元素

名稱 描述 必要
標頭 為具名標頭新增一或多個元素，以覆寫回應中標頭的預設驗證動作。 No

動作

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

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

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

可用動作：

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

使用方式

使用注意事項

  • 此原則只能在原則區段中使用一次。

記錄

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

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

對於效能的影響

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

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

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

範例

<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />

驗證錯誤

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 值：

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

相關內容

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