コンテンツの検証
適用対象: すべての API Management レベル
validate-content ポリシーは 1 つ以上のサポートされているスキーマに対して、要求または応答の本文のサイズまたはコンテンツを検証します。
次の表は、ポリシーがサポートするスキーマ形式と要求または応答のコンテンツの種類を示しています。 コンテンツの種類の値では大文字と小文字が区別されません。
| フォーマット | コンテンツの種類 |
|---|---|
| JSON | 例: application/jsonapplication/hal+json |
| XML | 例: application/xml |
| SOAP | 使用可能な値: application/soap+xml (SOAP 1.2 API の場合)text/xml (SOAP 1.1 API の場合) |
Note
この検証ポリシーで使用できる API スキーマの最大サイズは 4 MB です。 スキーマがこの制限を超えた場合、検証ポリシーは実行時にエラーを返します。 これを増やすには、サポートにお問い合わせください。
検証されるコンテンツ
ポリシーは、スキーマに対する要求または応答の次のコンテンツを検証します:
- すべての必須プロパティの存在。
- スキーマに
additionalPropertiesフィールドが設定されている場合、追加のプロパティの有無。allow-additional-properties属性でオーバーライドされる場合があります。 - すべてのプロパティのタイプ。 たとえば、スキーマでプロパティを整数として指定する場合、要求 (または応答) には整数を含める必要があり、文字列などの別の型は含めないようにする必要があります。
- スキーマで指定されている場合のプロパティの形式 で、たとえば、正規表現 (
patternキーワードが指定されている場合)、minimum整数など。
ヒント
スキーマで使用できる正規表現パターン制約の例については、OWASP 検証正規表現リポジトリを参照してください。
Note
ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。
ポリシー ステートメント
<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>
属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| unspecified-content-type-action | API スキーマで指定されていないコンテンツ タイプの要求または応答に対して実行するアクション。 ポリシー式を使用できます。 | はい | なし |
| max-size | Content-Length ヘッダーに対してチェックされる、要求または応答の本文の最大長 (バイト単位)。 要求本文または応答本文が圧縮されている場合、この値は圧縮解除された長さになります。 許可される最大値: 4 MB。 ポリシー式を使用できます。 |
はい | なし |
| size-exceeded-action | 本文が max-size で指定されたサイズを超えている要求または応答に対して実行するアクション。 ポリシー式を使用できます。 |
はい | なし |
| errors-variable-name | 検証エラーをログに記録する context.Variables の変数の名前。 ポリシー式は使用できません。 |
いいえ | 該当なし |
要素
| 名前 | 説明 | 必須 |
|---|---|---|
| content-type-map | この要素を追加して、受信要求または応答のコンテンツ タイプを、検証をトリガーするために使用される別のコンテンツ タイプにマップします。 | いいえ |
| コンテンツ | これらの要素を 1 つ以上追加して、要求または応答のコンテンツ タイプまたはマップされたコンテンツ タイプを検証し、指定されたアクションを実行します。 | いいえ |
content-type-map の属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| any-content-type-value | 受信コンテンツ タイプに関係なく、要求または応答の本文の検証に使用されるコンテンツ タイプ。 ポリシー式は使用できません。 | いいえ | 該当なし |
| missing-content-type-value | 受信コンテンツ タイプが見つからないか空の場合に、要求または応答の本文の検証に使用されるコンテンツ タイプ。 ポリシー式は使用できません。 | いいえ | 該当なし |
content-type-map-elements
| 名前 | 説明 | 必須 |
|---|---|---|
| type | これらの要素を 1 つ以上追加して、受信コンテンツ タイプを、要求または応答の本文の検証に使用されるコンテンツ タイプにマップします。 from を使用して既知の受信コンテンツ タイプを指定するか、when とポリシー式を使用して、条件に一致する受信コンテンツ タイプを指定します。 指定されている場合に、any-content-type-value と missing-content-type-value のマッピングをオーバーライドします。 |
いいえ |
content の属性
| 属性 | 説明 | 必要 | Default |
|---|---|---|---|
| type | 本文の検証を実行するコンテンツ タイプ。指定されている場合は、コンテンツ タイプ ヘッダーまたは content-type-mapping でマップされている値に対してチェックされます。 空の場合は、API スキーマで指定されているすべてのコンテンツ タイプに適用されます。SOAP 要求と応答を検証するには ( validate-as 属性が "soap" に設定されます)、SOAP 1.2 API の場合は type を application/soap+xml に設定し、SOAP 1.1 API の場合は text/xml に設定します。 |
いいえ | なし |
| validate-as | type が一致する要求または応答の本文の検証に使用する検証エンジン。 サポートされている値: "json"、"xml"、"soap"。"soap" を指定すると、要求または応答の XML が SOAP エンベロープから抽出され、XML スキーマに対して検証されます。 |
はい | 該当なし |
| schema-id | コンテンツの検証のために API Management インスタンスに追加された既存のスキーマの名前。 指定しない場合、API 定義の既定のスキーマが使用されます。 | いいえ | 該当なし |
| schema-ref | schema-id で指定されたJSON スキーマの場合は、JSON ドキュメント内の有効なローカル参照パスへの省略可能な参照。 例: #/components/schemas/address. この属性は、API Management が有効な JSON スキーマとして処理する JSON オブジェクトを返します。XML スキーマの場合、 schema-ref はサポートされておらず、最上位レベルのスキーマ要素を VML 要求または応答ペイロードのルートとして使用できます。 検証では、XML 要求または応答のペイロード ルートから始まるすべての要素が、指定された XML スキーマに準拠しているかどうかがチェックされます。 |
いいえ | 該当なし |
| allow-additional-properties | ブール値。 JSON スキーマの場合、スキーマで構成された additionalProperties 値のランタイム オーバーライドを実装するかどうかを指定します。- true: JSON スキーマの additionalProperties フィールドが追加のプロパティを許可しないように構成されている場合でも、要求または応答本文で追加のプロパティを許可します。 - false: JSON スキーマの additionalProperties フィールドが追加のプロパティを許可するように構成されている場合でも、要求または応答本文で追加のプロパティを許可しません。属性が指定されていない場合、ポリシーはスキーマ内の additionalProperties フィールドの構成に従って追加のプロパティを検証します。 |
いいえ | N/A |
| case-insensitive-property-names | ブール値。 JSON スキーマの場合、大文字と小文字を区別せずに JSON オブジェクトのプロパティ名を比較するかどうかを指定します。 - true: 大文字と小文字を区別しないでプロパティ名を比較します。 - false: 大文字と小文字を区別してプロパティ名を比較します。 |
いいえ | false |
アクション
コンテンツ検証ポリシーには、API 要求または応答内のエンティティを API スキーマに対して検証するときに API Management によって行われるアクションを指定する属性が 1 つ以上含まれています。
アクションは、API スキーマで表されている要素に対して指定できます。ポリシーによっては、API スキーマで表されていない要素に対しても指定できます。
ポリシーの子要素に指定されたアクションは、その親に対して指定されたアクションをオーバーライドします。
使用可能なアクション:
| アクション | 説明 |
|---|---|
| ignore | 検証をスキップします。 |
| 回避 (prevent) | 要求または応答の処理をブロックし、詳細な検証エラーをログに記録して、エラーを返します。 最初のエラー セットが検出されると、処理が中断されます。 |
| 検出 (detect) | 要求または応答の処理を中断することなく、検証エラーをログに記録します。 |
使用
- ポリシー セクション: 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 インスタンスにスキーマを追加するには、次のようにします。
portal で、API Management インスタンスに移動します。
左側のメニューの [API] セクションで、[スキーマ]>[+ 追加] を選択します。
[スキーマの作成] ウィンドウで、次の操作を行います。
- スキーマの名前 (ID) を入力します。
- [スキーマの種類] で、[JSON] または [XML] を選択します。
- [Description](説明) を入力します。
- [フォルダーの作成] で、次のいずれかの操作を行います。
- [新規作成] を選択し、スキーマを入力するか貼り付けます。
- [ファイルからインポート] または [URL からインポートする] を選択し、スキーマの場所を入力します。
注意
URL からスキーマをインポートするには、ブラウザーからインターネット経由でスキーマにアクセスできる必要があります。
- [保存] を選択します。
API Management により、相対 URI /schemas/<schemaId> にスキーマ リソースが追加され、[スキーマ] ページのリストにスキーマが表示されます。 スキーマを選択してプロパティを表示するか、スキーマ エディターで編集します。
注意
スキーマは、API Management インスタンスに追加された別のスキーマを相互参照する場合があります。 たとえば、次のような要素を使用して、API Management に追加された XML スキーマを含めます。<xs:include schemaLocation="/schemas/myschema" />
ヒント
WSDL および XSD スキーマの参照を解決し、生成されたスキーマを API Management に一括インポートするためのオープン ソース ツールが GitHub で提供されています。
例
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 が含まれます。
| 名前 | 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) |
次の表に、検証エラーで考えられるすべての原因の値と、考えられるメッセージの値を示します。
| 理由 | メッセージ |
|---|---|
| 正しくない要求 | {詳細} (コンテキスト変数用)、{パブリック応答} (クライアント用) |
| 応答が許可されない | {詳細} (コンテキスト変数用)、{パブリック応答} (クライアント用) |
関連ポリシー
関連するコンテンツ
ポリシーに対する処理の詳細については、次のトピックを参照してください。