次の方法で共有

状態コードを検証する

  • [アーティクル]

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

validate-status-code ポリシーは、API スキーマに対して応答の HTTP 状態コードを検証します。 このポリシーは、スタック トレースを含む可能性があるバックエンド エラーの漏えいを防ぐために使用できます。

注意

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

Note

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

ポリシー ステートメント

<validate-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

属性

属性 説明 必要 Default
unspecified-status-code-action API スキーマで指定されていない応答の HTTP 状態コードに対して実行するアクション。 ポリシー式を使用できます。 はい なし
errors-variable-name 検証エラーをログに記録する context.Variables の変数の名前。 ポリシー式は使用できません。 いいえ 該当なし

要素

名前 説明 必須
status-code HTTP 状態コードに 1 つ以上の要素を追加して、応答の状態コードに対する既定の検証アクションをオーバーライドします。 No

status-code の属性

属性 説明 必要 Default
code 検証アクションをオーバーライドする HTTP 状態コード。 はい なし
action API スキーマで指定されていない、一致する状態コードに対して実行するアクション。 状態コードが API スキーマで指定されている場合、このオーバーライドは有効になりません。 はい 該当なし

アクション

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

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

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

使用可能なアクション:

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

使用

使用上の注意

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

ログ

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

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

パフォーマンスへの影響

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

  • API スキーマのサイズが大きいほど、スループットが低下します。
  • 要求または応答のペイロードが大きいほど、スループットが低下します。
  • API スキーマのサイズは、ペイロードのサイズよりもパフォーマンスに大きな影響を与えます。
  • 数メガバイトのサイズの API スキーマに対して検証を行うと、一部の条件下で要求または応答のタイムアウトが発生する可能性があります。 影響は、サービスの従量課金レベルと開発者レベルでより顕著になります。

API スループットに対する検証ポリシーの影響を評価するには、想定される運用ワークロードでロード テストを実行することをお勧めします。

例

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

検証エラー

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)

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

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

関連するコンテンツ

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