コンテンツの検証

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

validate-content ポリシーは 1 つ以上のサポートされているスキーマに対して、要求または応答の本文のサイズまたはコンテンツを検証します。

次の表は、ポリシーがサポートするスキーマ形式と要求または応答のコンテンツの種類を示しています。 コンテンツの種類の値では大文字と小文字が区別されません。

検証されるコンテンツ

ポリシーは、スキーマに対する要求または応答の次のコンテンツを検証します:

• すべての必須プロパティの存在。
• スキーマに additionalProperties フィールドが設定されている場合、追加のプロパティの有無。 allow-additional-properties 属性でオーバーライドされる場合があります。
• すべてのプロパティのタイプ。 たとえば、スキーマでプロパティを整数として指定する場合、要求 (または応答) には整数を含める必要があり、文字列などの別の型は含めないようにする必要があります。
• スキーマで指定されている場合のプロパティの形式 で、たとえば、正規表現 (patternキーワードが指定されている場合)、minimum整数など。

ポリシー ステートメント

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

属性

要素

content-type-map の属性

content-type-map-elements

content の属性

アクション

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

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

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

使用可能なアクション:

使用

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

ログ

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

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

パフォーマンスへの影響

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

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

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

コンテンツ検証用のスキーマ

既定では、要求または応答のコンテンツの検証では、API 定義の JSON または XML のスキーマが使用されます。 これらのスキーマは、OpenAPI または WSDL 仕様から API Management に API をインポートするときに、手動で指定することも、自動的に生成することもできます。

validate-content ポリシーを使用すると、必要に応じて、API Management インスタンスに追加し、API 定義の一部になっていない 1 つ以上の JSON スキーマまたは XML スキーマに対して検証を行うことができます。 API Management に追加したスキーマは、多くの API で再利用できます。

Azure portal を使用して API Management インスタンスにスキーマを追加するには、次のようにします。

1. portal で、API Management インスタンスに移動します。

2. 左側のメニューの [API] セクションで、[スキーマ]>[+ 追加] を選択します。

3. [スキーマの作成] ウィンドウで、次の操作を行います。

   1. スキーマの名前 (ID) を入力します。
   2. [スキーマの種類] で、[JSON] または [XML] を選択します。
   3. [Description](説明) を入力します。
   4. [フォルダーの作成] で、次のいずれかの操作を行います。
      • [新規作成] を選択し、スキーマを入力するか貼り付けます。
      • [ファイルからインポート] または [URL からインポートする] を選択し、スキーマの場所を入力します。

        注意

        URL からスキーマをインポートするには、ブラウザーからインターネット経由でスキーマにアクセスできる必要があります。

   5. [保存] を選択します。

   

API Management により、相対 URI /schemas/<schemaId> にスキーマ リソースが追加され、[スキーマ] ページのリストにスキーマが表示されます。 スキーマを選択してプロパティを表示するか、スキーマ エディターで編集します。

例

JSON スキーマの検証

次の例では、API Management は、コンテンツ タイプが空の要求、またはコンテンツ タイプのヘッダーが application/hal+json の要求を、コンテンツ タイプ application/json の要求として解釈します。 その後で、API Management は、API 定義で application/json コンテンツ タイプに対して定義されているスキーマに対して、検出モードで検証を実行します。 ペイロードが 100 KB を超えるメッセージはブロックされます。 スキーマの additionalProperties フィールドが追加のプロパティを許可するように構成されている場合でも、追加のプロパティを含む要求はブロックされます。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

SOAP スキーマの検証

次の例では、API Management は、受信コンテンツ タイプに関係なくどの要求も、コンテンツ タイプ application/soap+xml (SOAP 1.2 API によって使用されるコンテンツ タイプ) の要求として解釈します。 要求は、空のコンテンツ タイプ ヘッダー、text/xml のコンテンツ タイプヘッダー (SOAP 1.1 API で使用される)、または別のコンテンツ タイプ ヘッダーで受信することがあります。 次に、API Management は SOAP エンベロープから XML ペイロードを抽出し、"myschema" という名前のスキーマに対して防止モードの検証を実行します。 ペイロードが 100 KB を超えるメッセージはブロックされます。

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

検証エラー

API Management では、次の形式でコンテンツ検証エラーが生成されます。

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

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

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

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

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

関連ポリシー

• コンテンツの検証

関連するコンテンツ

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

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