驗證參數

發行項
03/25/2024

適用於：所有 API 管理層

該 validate-parameters 原則會根據 API 結構描述，在要求中驗證標頭、查詢或路徑參數。

重要

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

注意

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

注意

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

原則陳述式

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

屬性

屬性	描述	是必要欄位	預設
specified-parameter-action	API 結構描述中指定的要求參數所需執行的動作。在 `headers`、`query` 或 `path` 元素中提供時，值會覆寫 `validate-parameters` 元素中的 `specified-parameter-action` 值。允許使用原則運算式。	Yes	N/A
unspecified-parameter-action	API 結構描述中未指定的要求參數所需執行的動作。在 `headers` 或 `query` 元素中提供時，值會覆寫 `validate-parameters` 元素中的 `unspecified-parameter-action` 值。允許使用原則運算式。	Yes	N/A
errors-variable-name	要記錄驗證錯誤的 `context.Variables` 中變數名稱。不允許使用原則運算式。	No	N/A

元素

名稱	描述	必要
標題	新增此元素和一或多個 `parameter` 子元素，以覆寫要求中特定具名參數的預設驗證動作。如果在 API 結構描述中指定該參數，此值會覆寫較高層級 `specified-parameter-action` 的組態。如果未在 API 結構描述中指定該參數，此值會覆寫較高層級 `unspecified-parameter-action` 的組態。	No
query	新增此元素和一或多個 `parameter` 子元素，以覆寫要求中特定具名查詢參數的預設驗證動作。如果在 API 結構描述中指定該參數，此值會覆寫較高層級 `specified-parameter-action` 的組態。如果未在 API 結構描述中指定該參數，此值會覆寫較高層級 `unspecified-parameter-action` 的組態。	No
path	新增此元素和一或多個 `parameter` 子元素，以覆寫要求中特定 URL 路徑參數的預設驗證動作。如果在 API 結構描述中指定該參數，此值會覆寫較高層級 `specified-parameter-action` 的組態。如果未在 API 結構描述中指定該參數，此值會覆寫較高層級 `unspecified-parameter-action` 的組態。	No

動作

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

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

可用動作：

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

使用方式

原則區段︰inbound
原則範圍︰全域、工作區、產品、API、作業
閘道： 傳統、v2、耗用量、自我裝載

使用注意事項

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

記錄

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

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

對於效能的影響

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

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

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

範例

在此範例中，所有查詢和路徑參數都會在預防模式和偵測模式的標頭中進行驗證。已覆寫數個標頭參數的驗證：

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

驗證錯誤

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

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

內容驗證

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

驗證參數

原則陳述式

屬性

元素

動作

使用方式

使用注意事項

記錄

對於效能的影響

範例

驗證錯誤

相關原則

相關內容

其他資源