SOAPMessageValidation ポリシー

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

  • XSD スキーマに対する XML メッセージの検証
  • WSDL 定義に対する SOAP メッセージの検証
  • JSON および XML メッセージの整形式の判別

UI におけるこのポリシーの名前は「SOAP Message Validation」ですが、SOAP メッセージ以外も検証します。このセクションでは、このポリシーを「Message Validation ポリシー」として取り上げます。

<MessageValidation> 要素

Message Validation ポリシーを定義します。

デフォルト値 下記の [デフォルト ポリシー] タブをご覧ください。
要否 省略可
複合オブジェクト
親要素 なし
子要素 <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>

デフォルト ポリシー

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

<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>

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須? Description
name なし 必須

ポリシーの内部名。name 属性の値には、アルファベット、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

必要に応じて <DisplayName> 要素を使用して、管理 UI プロキシ エディタのポリシーに別の自然言語の名前でラベルを付けます。

continueOnError false 省略可 ポリシーが失敗したときにエラーを返すには、「false」に設定します。これはほとんどのポリシーで想定される挙動です。ポリシーが失敗した後でも、フローの実行を続行するには、「true」に設定します。
enabled true 省略可 ポリシーを適用するには、「true」に設定します。ポリシーを「無効」にするには、「false」に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性はサポートが終了しています。

次の例はそれぞれ、Message Validation ポリシーの使用方法を示しています。

1: XSD 検証

Message Validation ポリシーを使用して、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 Message Validation ポリシーを追加します。
    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 検証

Message Validation ポリシーを使用して、SOAP メッセージ リクエストのペイロードを WSDL に対して検証できます。

  1. 新しいリソース ファイルを作成します(例: 「example-wsdl.wsdl」)。
  2. プロキシ エンドポイントのプリフローに SOAP Message Validation ポリシーを追加します。
    1. <SOAPMessage> 要素の version 属性を、検証する SOAP プロトコルのバージョンに設定します。例: 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 Message Validation ポリシーを追加します。
  2. ポリシー定義から <ResourceURL> 要素、<SOAPMessage> 要素、<Element> 要素を削除します。

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

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. 次の例のように、API プロキシに POST リクエストを送信します。
    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 を使用する

Message Validation ポリシーで検証する XML ペイロードが別のスキーマを参照している場合、XSD ファイルの先頭に schemaLocation 属性の 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 つ以上定義する必要があります。スキーマを 1 つも参照していない場合、Message Validation ポリシーは失敗します。

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

<SOAPMessage>

Message Validation ポリシーが検証する 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(9 ポイント)をご覧ください。

<Source>

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

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

デフォルト値 リクエスト
要否 省略可
文字列
親要素 <MessageValidation>
子要素 なし

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

構文

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

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

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

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

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

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

エラーコード

Edge ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います

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

ランタイム エラー

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

障害コード HTTP ステータス 原因 解決方法
steps.messagevalidation.SourceMessageNotAvailable 500

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

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

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

メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Edge フロー変数 requestresponsemessage はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。

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 から入手できます。

関連トピック