パラメーターを検証する:

適用対象: すべての API Management レベル

validate-parameters ポリシーは、API スキーマに対して要求のヘッダー、クエリ、またはパス パラメーターを検証します。

重要

2021-01-01-preview より前のバージョンの管理 API を使用して API をインポートした場合、validate-parameters ポリシーが機能しない可能性があります。 管理 API バージョン 2021-01-01-preview 以降を使用して、API を再インポートすることが必要になる場合があります。

注意

この検証ポリシーで使用できる API スキーマの最大サイズは 4 MB です。 スキーマがこの制限を超えた場合、検証ポリシーは実行時にエラーを返します。 これを増やすには、サポートにお問い合わせください。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

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

属性

属性	説明	必要	Default
specified-parameter-action	API スキーマで指定された要求パラメーターに対して実行するアクション。 headers、query、または path 要素で指定された場合、 値は validate-parameters 要素内の specified-parameter-action の値をオーバーライドします。 ポリシー式を使用できます。	はい	なし
unspecified-parameter-action	API スキーマで指定されていない要求パラメーターに対して実行するアクション。 headers または query 要素で指定された場合、 値は validate-parameters 要素内の unspecified-parameter-action の値をオーバーライドします。 ポリシー式を使用できます。	はい	なし
errors-variable-name	検証エラーをログに記録する context.Variables の変数の名前。 ポリシー式は使用できません。	いいえ	該当なし

要素

名前	説明	必須
headers	この要素と 1 つ以上の parameter サブ要素を追加して、要求内の特定の名前付きパラメーターの既定の検証アクションをオーバーライドします。 パラメーターが API スキーマで指定されている場合、この値は上位レベルの specified-parameter-action 構成をオーバーライドします。 パラメーターが API スキーマで指定されていない場合、この値は上位レベルの unspecified-parameter-action 構成をオーバーライドします。	いいえ
query	この要素と 1 つ以上の parameter サブ要素を追加して、要求内の特定の名前付きクエリ パラメーターの既定の検証アクションをオーバーライドします。 パラメーターが API スキーマで指定されている場合、この値は上位レベルの specified-parameter-action 構成をオーバーライドします。 パラメーターが API スキーマで指定されていない場合、この値は上位レベルの unspecified-parameter-action 構成をオーバーライドします。	いいえ
path	この要素と 1 つ以上の parameter サブ要素を追加して、要求内の特定の URL パス パラメーターの既定の検証アクションをオーバーライドします。 パラメーターが API スキーマで指定されている場合、この値は上位レベルの specified-parameter-action 構成をオーバーライドします。 パラメーターが API スキーマで指定されていない場合、この値は上位レベルの unspecified-parameter-action 構成をオーバーライドします。	No

アクション

コンテンツ検証ポリシーには、API 要求または応答内のエンティティを API スキーマに対して検証するときに API Management によって行われるアクションを指定する属性が 1 つ以上含まれています。

• アクションは、API スキーマで表されている要素に対して指定できます。ポリシーによっては、API スキーマで表されていない要素に対しても指定できます。

• ポリシーの子要素に指定されたアクションは、その親に対して指定されたアクションをオーバーライドします。

使用可能なアクション:

アクション	説明
ignore	検証をスキップします。
回避 (prevent)	要求または応答の処理をブロックし、詳細な検証エラーをログに記録して、エラーを返します。 最初のエラー セットが検出されると、処理が中断されます。
検出 (detect)	要求または応答の処理を中断することなく、検証エラーをログに記録します。

使用

• ポリシー セクション: inbound
• ポリシー スコープ: グローバル、ワークスペース、製品、API、操作
• ゲートウェイ: クラシック、v2、従量課金、セルフホステッド

使用上の注意

• このポリシーは、ポリシー セクションで一度だけ使用できます。

ログ

ポリシー実行中の検証エラーの詳細は、 ポリシーのルート要素の errors-variable-name 属性で指定されている context.Variables の変数に記録されます。 prevent アクションで構成されている場合、検証エラーによってその後の要求または応答の処理がブロックされ、検証エラーは context.LastError プロパティにも反映されます。

エラーを調査するには、 トレース ポリシーを使用して、コンテキスト変数から Application Insights にエラーを記録します。

パフォーマンスへの影響

検証ポリシーを追加すると、API のスループットに影響を与える可能性があります。 一般論としては、次のような原則があります。

• API スキーマのサイズが大きいほど、スループットが低下します。
• 要求または応答のペイロードが大きいほど、スループットが低下します。
• API スキーマのサイズは、ペイロードのサイズよりもパフォーマンスに大きな影響を与えます。
• 数メガバイトのサイズの 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 Management では、次の形式でコンテンツ検証エラーが生成されます。

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

次の表に、検証ポリシーで発生する可能性があるすべてのエラーを示します。

• 詳細: エラーを調査するために使用できます。 一般に共有するためのものではありません。
• パブリック応答: クライアントに返されるエラー。 実装の詳細は漏えいしません。

検証ポリシーで prevent アクションを指定し、エラーが発生すると、API Management からの応答には、受信セクションでポリシーが適用されている場合は HTTP 状態コード 400、送信セクションでポリシーが適用されている場合は 502 が含まれます。

名前	Type	検証規則	詳細	パブリック応答	操作
validate-content
	RequestBody	SizeLimit	要求の本文の長さは {size} バイトで、構成されている制限の {maxSize} バイトを超えています。	要求の本文の長さは {size} バイトで、制限の {maxSize} バイトを超えています。	検出 (detect) /回避 (prevent)
	ResponseBody	SizeLimit	応答の本文の長さは {size} バイトで、構成されている制限の {maxSize} バイトを超えています。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{messageContentType}	RequestBody	指定されていません。	指定されていないコンテンツ タイプ {messageContentType} は許可されません。	指定されていないコンテンツ タイプ {messageContentType} は許可されません。	検出 (detect) /回避 (prevent)
{messageContentType}	ResponseBody	指定されていません。	指定されていないコンテンツ タイプ {messageContentType} は許可されません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	ApiSchema		API のスキーマが存在しないか、解決できませんでした。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	ApiSchema		API のスキーマで定義が指定されていません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	API のスキーマに、コンテンツ タイプ {messageContentType} に関連付けられている定義 {definitionName} が含まれていません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{messageContentType}	RequestBody	IncorrectMessage	要求の本文が、コンテンツ タイプ {messageContentType} に関連付けられている定義 {definitionName} に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	要求の本文が、コンテンツ タイプ {messageContentType} に関連付けられている定義 {definitionName} に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	検出 (detect) /回避 (prevent)
{messageContentType}	ResponseBody	IncorrectMessage	応答の本文が、コンテンツ タイプ {messageContentType} に関連付けられている定義 {definitionName} に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	RequestBody	ValidationException	コンテンツ タイプ {messageContentType} に対して、要求の本文を検証できません。 {exception details}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	ResponseBody	ValidationException	コンテンツ タイプ {messageContentType} に対して、応答の本文を検証できません。 {exception details}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	指定されていません。	指定されていない {path parameter / query parameter / header} {paramName} は許可されません。	指定されていない {path parameter / query parameter / header} {paramName} は許可されません。	検出 (detect) /回避 (prevent)
{headerName}	ResponseHeader	指定されていません。	指定されていないヘッダー {headerName} は許可されません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	ApiSchema		API のスキーマが存在しないか、解決できませんでした。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
	ApiSchema		API スキーマで定義が指定されていません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	API のスキーマに、{query parameter / path parameter / header} {paramName} に関連付けられている定義 {definitionName} が含まれていません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	要求では、{query parameter / path parameter / header} {paramName} に対して複数の値を含めることはできません。	要求では、{query parameter / path parameter / header} {paramName} に対して複数の値を含めることはできません。	検出 (detect) /回避 (prevent)
{headerName}	ResponseHeader	IncorrectMessage	応答では、ヘッダー {headerName} に対して複数の値を含めることはできません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	{query parameter / path parameter / header} {paramName} の値が定義に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	{query parameter / path parameter / header} {paramName} の値が定義に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	検出 (detect) /回避 (prevent)
{headerName}	ResponseHeader	IncorrectMessage	ヘッダー {headerName} の値が定義に準拠していません。 {valError.Message} 行: {valError.LineNumber}、位置: {valError.LinePosition}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	{query parameter / path parameter / header} {paramName} の値を、定義に従って解析できません。 {ex.Message}	{query parameter / path parameter / header} {paramName} の値を、定義に従って解析できませんでした。 {ex.Message}	検出 (detect) /回避 (prevent)
{headerName}	ResponseHeader	IncorrectMessage	ヘッダー {headerName} の値を、定義に従って解析できませんでした。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{paramName}	QueryParameter / PathParameter / RequestHeader	ValidationError	{Query parameter / Path parameter / Header} {paramName} を検証できません。 {exception details}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
{headerName}	ResponseHeader	ValidationError	ヘッダー {headerName} を検証できません。 {exception details}	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)
validate-status-code
{status-code}	StatusCode	指定されていません。	応答状態コード {status-code} は許可されません。	内部エラーにより、要求を処理できませんでした。 API の所有者に問い合わせてください。	検出 (detect) /回避 (prevent)

次の表に、検証エラーで考えられるすべての原因の値と、考えられるメッセージの値を示します。

理由	メッセージ
正しくない要求	{詳細} (コンテキスト変数用)、{パブリック応答} (クライアント用)
応答が許可されない	{詳細} (コンテキスト変数用)、{パブリック応答} (クライアント用)

関連ポリシー

• コンテンツの検証

関連するコンテンツ

ポリシーに対する処理の詳細については、次のトピックを参照してください。

• チュートリアル:API を変換および保護する
• ポリシー ステートメントとその設定の一覧に関するポリシー リファレンス
• ポリシー式
• ポリシーの設定または編集
• ポリシー構成を再利用する
• ポリシー スニペットのリポジトリ
• Microsoft Copilot for Azure を使用してポリシーを作成する