ヘッダーを検証する
適用対象: すべての API Management レベル
validate-headers
ポリシーは、API スキーマに対して応答ヘッダーを検証します。
重要
2021-01-01-preview
より前のバージョンの管理 API を使用して API をインポートした場合、validate-headers
ポリシーが機能しない可能性があります。 管理 API バージョン 2021-01-01-preview
以降を使用して、API を再インポートすることが必要になる場合があります。
注意
この検証ポリシーで使用できる API スキーマの最大サイズは 4 MB です。 スキーマがこの制限を超えた場合、検証ポリシーは実行時にエラーを返します。 これを増やすには、サポートにお問い合わせください。
Note
ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。
ポリシー ステートメント
<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>
属性
属性 | 説明 | 必要 | Default |
---|---|---|---|
specified-header-action | API スキーマで指定された応答ヘッダーに対して実行するアクション。 ポリシー式を使用できます。 | はい | なし |
unspecified-header-action | API スキーマで指定されていない応答ヘッダーに対して実行するアクション。 ポリシー式を使用できます。 | はい | なし |
errors-variable-name | 検証エラーをログに記録する context.Variables の変数の名前。 ポリシー式は使用できません。 |
いいえ | 該当なし |
要素
名前 | 説明 | 必須 |
---|---|---|
header | 名前付きヘッダーに 1 つ以上の要素を追加して、応答のヘッダーに対する既定の検証アクションをオーバーライドします。 | No |
アクション
コンテンツ検証ポリシーには、API 要求または応答内のエンティティを API スキーマに対して検証するときに API Management によって行われるアクションを指定する属性が 1 つ以上含まれています。
アクションは、API スキーマで表されている要素に対して指定できます。ポリシーによっては、API スキーマで表されていない要素に対しても指定できます。
ポリシーの子要素に指定されたアクションは、その親に対して指定されたアクションをオーバーライドします。
使用可能なアクション:
アクション | 説明 |
---|---|
ignore | 検証をスキップします。 |
回避 (prevent) | 要求または応答の処理をブロックし、詳細な検証エラーをログに記録して、エラーを返します。 最初のエラー セットが検出されると、処理が中断されます。 |
検出 (detect) | 要求または応答の処理を中断することなく、検証エラーをログに記録します。 |
使用
- ポリシー セクション: outbound、on-error
- ポリシー スコープ: グローバル、ワークスペース、製品、API、操作
- ゲートウェイ: クラシック、v2、従量課金、セルフホステッド、ワークスペース
使用上の注意
- このポリシーは、ポリシー セクションで一度だけ使用できます。
ログ
ポリシー実行中の検証エラーの詳細は、 ポリシーのルート要素の errors-variable-name
属性で指定されている context.Variables
の変数に記録されます。 prevent
アクションで構成されている場合、検証エラーによってその後の要求または応答の処理がブロックされ、検証エラーは context.LastError
プロパティにも反映されます。
エラーを調査するには、 トレース ポリシーを使用して、コンテキスト変数から Application Insights にエラーを記録します。
パフォーマンスへの影響
検証ポリシーを追加すると、API のスループットに影響を与える可能性があります。 一般論としては、次のような原則があります。
- API スキーマのサイズが大きいほど、スループットが低下します。
- 要求または応答のペイロードが大きいほど、スループットが低下します。
- API スキーマのサイズは、ペイロードのサイズよりもパフォーマンスに大きな影響を与えます。
- 数メガバイトのサイズの API スキーマに対して検証を行うと、一部の条件下で要求または応答のタイムアウトが発生する可能性があります。 影響は、サービスの従量課金レベルと開発者レベルでより顕著になります。
API スループットに対する検証ポリシーの影響を評価するには、想定される運用ワークロードでロード テストを実行することをお勧めします。
例
<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />
検証エラー
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 を変換および保護する
- ポリシー ステートメントとその設定の一覧に関するポリシー リファレンス
- ポリシー式
- ポリシーの設定または編集
- ポリシー構成を再利用する
- ポリシー スニペットのリポジトリ
- Azure で Microsoft Copilot を使用してポリシーを作成する