SOAPMessageValidation ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

ポリシー アイコン

SOAPMessageValidation ポリシーは次の処理を行います。

  • XSD スキーマに対する XML メッセージの検証
  • WSDL 定義に対する SOAP メッセージの検証
  • JSON および XML メッセージの形式が正しいかどうかの判別

UI では、このポリシーの名前が SOAPMessageValidation となっていますが、SOAP メッセージ以外の検証も行います。このセクションでは、このポリシーを MessageValidation ポリシーと表記します。

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

<MessageValidation> 要素

MessageValidation ポリシーを定義します。

デフォルト値 下記の [デフォルト ポリシー] タブをご覧ください。
必須かどうか 省略可
型 複合オブジェクト
親要素 なし
子要素 <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

構文

<MessageValidation> 要素の構文は次のとおりです。

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

デフォルト ポリシー

次の例は、Apigee UI でフローに MessageValidation ポリシーを追加したときのデフォルト設定を示しています。

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

例

次の例は、MessageValidation ポリシーの使用方法を示しています。

1: XSD 検証

MessageValidation ポリシーを使用して、XML メッセージ リクエストのペイロードが XSD スキーマに準拠しているかどうか検証できます。

  1. 新しい XSD リソース ファイルを作成します。例: note-schema.xsd: 
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="note">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="to" type="xs:string"/>
        <xs:element name="from" type="xs:string"/>
        <xs:element name="heading" type="xs:string"/>
        <xs:element name="body" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
  2. プロキシ エンドポイントのプリフローに SOAP MessageValidation ポリシーを追加します。
    1. <ResourceURL> 要素を使用して、XSD リソース ファイルの場所を指定します。次に例を示します。 
      ...
  <ResourceURL>xsd://note-schema.xsd</ResourceURL>
...
    2. ポリシー定義から <SOAPMessage> 要素と <Element> 要素を削除します。

    ポリシー定義は次のようになります。

    <MessageValidation continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My XML Validator</DisplayName>
  <Properties/>
  <Source>request</Source>
  <ResourceURL>xsd://note-schema.xsd</ResourceURL>
</MessageValidation>
  3. 次の例に示すように、XML をメッセージ ペイロードとして使用して、API プロキシに POST リクエストを送信します。
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
</note>'

    Content-type ヘッダーが application/xml に設定されていることに注意してください。

    ペイロードのデータファイルを作成して、次のようなコマンドで参照することもできます。

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  --data '@../examples/note-payload.xml'

HTTP 200 レスポンスが返されます。ターゲット エンドポイントによっては、リクエストに関する追加の詳細情報を受け取る場合があります。たとえば、ターゲット エンドポイントとして http://httpbin.org/post を使用し、-v（詳細）出力を指定すると、レスポンスは次のようになります。

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

XSD 検証が機能していることを確認するには、リクエストの本文に別のタグを挿入してみてください。次に例を示します。

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

検証エラーが返されます。

2: SOAP 検証

MessageValidation ポリシーを使用して、SOAP メッセージ リクエストのペイロードが WSDL に準拠しているかどうか検証できます。

  1. 新しい WSDL リソース ファイルを作成します。（例: 「example-wsdl.wsdl」）。
  2. プロキシ エンドポイントのプリフローに SOAP MessageValidation ポリシーを追加します。
    1. 検証する SOAP プロトコルのバージョンを <SOAPMessage> 要素の version 属性に設定します。たとえば、1.1 を設定します。 
      ...
  <SOAPMessage version="1.1"/>
...
    2. 検証する要素を <Element> 要素に設定します。 
      ...
  <Element namespace="https://example.com/gateway">getID</Element>
...

      <Element> は、SOAP リクエストのエンベロープの <Body> 要素の下にある最初の子を指定します。

      その子の名前空間を namespace 属性に設定します。

    3. <ResourceURL> 要素を使用して、WSDL リソース ファイルの場所を指定します。次に例を示します。 
      ...
  <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

    ポリシー定義は次のようになります。

    <MessageValidation continueOnError="false"
    enabled="true" name="validateSOAPRequest">
  <DisplayName>My SOAP Validator</DisplayName>
  <Properties/>
  <Source>request</Source>
  <SOAPMessage version="1.1"/>
  <Element namespace="https://example.com/gateway">getID</Element>
  <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
</MessageValidation>
  3. 次の例に示すように、SOAP エンベロープをメッセージ ペイロードとして API プロキシに POST リクエストを送信します。
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
  <soapenv:Header/>
  <soapenv:Body>
    <prox:getID>
      <typ:MyType>
        <typ:ID>42</typ:ID>
      </typ:MyType>
    </prox:getID>
  </soapenv:Body>
</soapenv:Envelope>'

    Content-type ヘッダーは「application/xml」に設定されています。

    ペイロードのデータファイルを作成して、次のようなコマンドで参照することもできます。

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  --data '@../examples/soap-payload.xml'

HTTP 200 レスポンスが返されます。ターゲット エンドポイントによっては、リクエストに関する追加の詳細情報を受け取る場合があります。たとえば、http://httpbin.org/post をターゲット エンドポイントとして使用する場合、レスポンスは次のようになります。

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: 整形式の XML / JSON

Message Validation ポリシーを使用して、JSON または XML のメッセージ ペイロードの形式が正しいことを確認できます（検証とは異なります）。このポリシーにより、構造と内容が以下のような認められた基準を満たしていることが保証されます。

  • 単一のルート要素があること
  • コンテンツに不正な文字がないこと
  • オブジェクトとタグが正しくネストされていること
  • 開始タグと終了タグが一致していること

整形式の XML または JSON ペイロードをチェックするには:

  1. プロキシ エンドポイントのプリフローに SOAP MessageValidation ポリシーを追加します。
  2. ポリシー定義から <ResourceURL> 要素、<SOAPMessage> 要素、<Element> 要素を削除します。

    ポリシー定義は次のようになります。

    <MessageValidation async="false" continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My JSON Checker</DisplayName>
  <Properties/>
  <Source>request</Source>
</MessageValidation>
  3. 次の例のように、POST リクエストを API プロキシに送信します。
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
  -d '{
"note": {
  "to": "Fred Rogers",
  "from": "Nick Danger",
  "header": "Greetings from my neighborhood",
  "body": "Just writing to say hello."
  }
}'

    Content-type ヘッダーが application/json に設定されていることに注意してください。

    整形式の XML ファイルの形式が正しいかどうかを確認するには、XML をメッセージ ペイロードとして使用し、Content-type を application/xml に設定します。

HTTP 200 レスポンスが返されます。正しい形式の XML または JSON が含まれていないメッセージ ペイロードを送信すると、steps.messagevalidation.Failed エラーが返されます。

子要素のリファレンス

このセクションでは、<MessageValidation> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値 なし
必須かどうか 省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
型 文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<Element>

検証するメッセージの要素を指定します。これは、SOAP リクエストのエンベロープの <Body> 要素の下にある最初の子です。

デフォルト値 sampleObject
必須かどうか 省略可
型 文字列
親要素 <MessageValidation>
子要素 なし

<Element> 要素の構文は次のとおりです。

構文

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

例 1

次の例では、検証する単一の要素を定義しています。

...
<Element namespace="https://example.com/gateway">getID</Element>
...

例 2

複数の <Element> 要素を追加することで、検証する要素を 1 つ以上指定できます。

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

<Element> 要素には次の属性があります。

属性 デフォルト 必須かどうか 説明
namespace 「http://sample.com」 省略可 検証される要素の名前空間を定義します。

<ResourceURL>

ソース メッセージの検証に使用される XSD スキーマまたは WSDL 定義を識別します。

デフォルト値 wsdl://display_name.wsdl
必須かどうか 省略可
型 文字列
親要素 <MessageValidation>
子要素 なし

<ResourceURL> 要素の構文は次のとおりです。

構文

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

例

XML ファイルの場合:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

WSDL の場合:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

<ResourceURL> の値は、API プロキシのリソース ファイルを参照する必要があります。HTTP や HTTPS 経由で外部リソースを参照することはできません。

<ResourceURL> に値を指定しない場合、Content-type ヘッダーが application/json または application/xml であれば、メッセージが整形式の JSON または XML であるかどうか検証されます。

<ResourceURL> 要素には子要素や属性はありません。

検証に XSD を使用する

MessageValidation ポリシーで検証する XML ペイロードが別のスキーマを参照している場合、schemaLocation 属性の XSD ファイルに接頭辞 xsd を付ける必要があります。

次のスキーマの例は、複数の XSD で構成されています。

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

検証に WSDL を使用する

WSDL には少なくとも 1 つスキーマを定義する必要があります。スキーマが参照されていない場合、MessageValidation ポリシーは失敗します。

スキーマの最大インポート深度は 10 です。インポートのネスト数がこの値を超えると、MessageValidation ポリシーは失敗します。

<SOAPMessage>

MessageValidation ポリシーが検証する SOAP バージョンを定義します。

デフォルト値 なし
必須かどうか 省略可
型 なし
親要素 <MessageValidation>
子要素 なし

<SOAPMessage> 要素の構文は次のとおりです。

構文

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

例

...
<SOAPMessage version="1.1"/>
...

<SOAPMessage> 要素には次の属性があります。

属性 デフォルト 必須かどうか 説明
version なし 省略可 このポリシーが SOAP メッセージの検証に使用する SOAP バージョン。

有効な値は次のとおりです。

  • 「1.1」
  • 「1.2」
  • 1.1/1.2

詳細については、SOAP/1.1 と SOAP バージョン 1.2 の主な相違点をご覧ください。

<Source>

検証されるソース メッセージを識別します。この要素の値には、検証するメッセージの名前を設定します。

<Source> を設定しない場合、このポリシーはデフォルトで message になります。これは、すべてのペイロードを含むリクエスト メッセージ（リクエスト フロー内）全体またはレスポンス メッセージ（レスポンス フロー内）全体を参照します。リクエストまたはレスポンスを参照するように、request または response に明示的に設定することもできます。

デフォルト値 リクエスト
必須かどうか 省略可
型 文字列
親要素 <MessageValidation>
子要素 なし

<Source> 要素の構文は次のとおりです。

構文

...
  <Source>message_to_validate</Source>
...

例

...
<Source>request</Source>
...

message、request、response に加えて、<Source> の値をフロー内のメッセージ名に設定できます。ただし、その場合は、このポリシーを実行する前に、フロー内にその名前のカスタム メッセージを作成する必要があります。作成しないと、エラーが発生します。

メッセージ フローで <Source> の値を解決できない場合、またはメッセージ以外のタイプに解決される場合は、次のいずれかが発生します。

  • null 値の場合: Apigee により steps.messagevalidation.SourceMessageNotAvailable エラーがスローされます。
  • メッセージ以外のタイプの場合: Apigee により steps.messagevalidation.NonMessageVariable エラーがスローされます。

<Source> 要素に属性や子要素はありません。

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 修正
steps.messagevalidation.SourceMessageNotAvailable 500

このエラーは、ポリシーの <Source> 要素で指定された変数が次のいずれかである場合に発生します。

  • 範囲外（ポリシーが実行されている特定のフローで使用できない）
    • または
  • 解決不能（未定義）
steps.messagevalidation.NonMessageVariable 500

このエラーは、SOAPMessageValidation ポリシーの <Source> 要素がメッセージ型以外の変数に設定されている場合に発生します。

メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Apigee フロー変数 request、response、message はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。
steps.messagevalidation.Failed 500 このエラーは、SOAPMessageValidation ポリシーが、XSD スキーマまたは WSDL 定義に対する入力メッセージ ペイロードを検証できなかった場合に発生します。また、ペイロード メッセージ内の JSON または XML の形式が正しくない場合にも発生します。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因 修正
InvalidResourceType SOAPMessageValidation ポリシーの <ResourceURL> 要素が、ポリシーでサポートされていないリソースタイプに設定されています。
ResourceCompileFailed SOAPMessageValidation ポリシーの <ResourceURL> 要素で参照されているリソース スクリプトに、コンパイルを妨げるエラーが含まれています。
RootElementNameUnspecified SOAPMessageValidation ポリシーの <Element> 要素にルート要素の名前が含まれていません。
InvalidRootElementName SOAPMessageValidation ポリシーの <Element> 要素に、有効な要素の命名に関する XML ルールに準拠していないルート要素名が含まれています。

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。

関連トピック