SOAPMessageValidation ポリシー

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

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

この UI のポリシーの名前は「SOAP メッセージの検証」ですが、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>
    

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

属性 デフォルト 要否 説明
name なし 必須

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

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

continueOnError false 省略可 ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。ポリシーが失敗してもフロー実行を続行するには、true に設定します。
enabled true 省略可 ポリシーを適用するには「true」に設定します。ポリシーを「turn off」するには、「false」に設定します。false に設定すると、ポリシーがフローに接続されている場合でも適用されません。
async  not_interested 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. 新しい WSDL リソース ファイルを作成します(例: 「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. 次の例に示すように、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/xm」に設定します。

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

子要素のリファレンス

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

<DisplayName>

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

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

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

構文

    <PolicyElement>
      <DisplayName>policy_display_name</DisplayName>
      ...
    </PolicyElement>
    

    <AssignMessage>
      <DisplayName>My Validation Policy</DisplayName>
    </AssignMessage>
    

<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> 要素を追加します。

...
    <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 ペイロードが別のスキーマを参照する場合、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 つ以上定義する必要があります。スキーマを 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」

詳細については、From SOAP/1.1 to SOAP Version 1.2 in 9 points をご覧ください。

<Source>

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

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

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

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

構文

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

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

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

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

  • null 値の場合: Edge は steps.messagevalidation.SourceMessageNotAvailable エラーを返します。
  • メッセージ以外のタイプの場合: Edge は steps.messagevalidation.NonMessageVariable エラーを返します。

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

エラーコード

Edge ポリシーから返されるエラーは、エラーコードのリファレンスの説明のように一定の形式で提供されます。

このポリシーは、エラー レスポンスで次のエラーコードとエラー メッセージを返します。エラー処理の手順については、エラー処理をご覧ください。

エラーコード メッセージ
InvalidResourceType

InvalidResourceType MessageValidation {0}: Invalid Resource Type {1}.
    It should be xsd or wsdl. Context {2}
ResourceCompileFailed

ResourceCompileFailed MessageValidation {0}: Failed to compile resource
    {1}. Context {2}
RootElementNameUnspecified

RootElementNameUnspecified MessageValidation {0}: RootElement name is
    not specified
InvalidRootElementName

InvalidRootElementName MessageValidation {0}: RootElement name {1} is
    invalid
NonMessageVariable

NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable

SourceMessageNotAvailable {0} message is not available for
    MessageValidation: {1}
NoElements

Resource "{0}" has no element definitions
Failed

MessageValidation {0} failed with reason: "{1}"

スキーマ

各ポリシータイプは XML スキーマ(.xsd)によって定義されます。GitHub に参照用のポリシー スキーマが用意されています。

関連トピック