SOAPMessageValidation ポリシー

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

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

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

Message Validation ポリシーについて

利点

メッセージ検証には次の利点があります。

リクエストが準拠していないか不完全である場合、API を使用しているアプリデベロッパーにすぐに通知します。
正しく閉じられていない XML タグなど、リクエストの問題を特定します。
予期しない動作を引き起こす可能性のある構造を持つ XML または SOAP メッセージをブロックすることで、バックエンドサービスを保護します。
トラブルシューティング、フォーラムの検索、テクニカルサポートへの問い合わせのための時間を短縮します。
広く知られている XML スキーマが API ドキュメントの主要なコンポーネントになるように、XML スキーマの WSDL 定義に慣れ親しみ、検証エラーを排除することをデベロッパーに奨励します。

動画

Message Validation ポリシーの詳細については、次の動画をご覧ください。

動画	説明
XML リクエストの検証	Message Validation ポリシーを使用して API の XML リクエストを検証します。
JSON リクエストの検証	Message Validation ポリシーを使用して API の JSON リクエストを検証します。

`<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 スキーマに対して検証できます。

新しい 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>

プロキシエンドポイントのプリフローに 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>
```

次の例のように、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 に対して検証できます。

新しいリソースファイルを作成します（例: 「example-wsdl.wsdl」）。

WSDL をすべて表示

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="https://example.com/gateway"
    xmlns:tns="https://example.com/gateway"
    xmlns:types="https://example.com/gateway/types"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
  <wsdl:types>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        targetNamespace="https://example.com/gateway/types"
        elementFormDefault="qualified">
      <xsd:element name="MyType">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ID" nillable="false" minOccurs="1" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
    <schema attributeFormDefault="unqualified" elementFormDefault="qualified"
        targetNamespace="https://example.com/gateway"
        xmlns="http://www.w3.org/2001/XMLSchema">
      <xsd:import namespace="https://example.com/gateway/types"/>
      <element name="getID">
        <complexType>
          <sequence>
            <element ref="types:MyType"/>
          </sequence>
        </complexType>
      </element>
    </schema>
  </wsdl:types>

  <wsdl:message name="getRequest">
    <wsdl:part name="getRequest" element="tns:getID"/>
  </wsdl:message>
  <wsdl:message name="getResponse">
    <wsdl:part name="getResponse" element="tns:getID"/>
  </wsdl:message>

  <wsdl:portType name="PortType">
    <wsdl:operation name="get">
      <wsdl:input name="methodRequest" message="tns:getRequest"/>
      <wsdl:output name="methodResponse" message="tns:getResponse"/>
    </wsdl:operation>
  </wsdl:portType>

  <wsdl:service name="Gateway">
    <wsdl:port name="GatewaySoap" binding="tns:SoapBinding">
      <wsdlsoap:address location="https://example.com/gateway"/>
    </wsdl:port>
  </wsdl:service>

  <wsdl:binding name="SoapBinding" type="tns:PortType">
    <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

    <wsdl:operation name="get">
      <wsdlsoap:operation soapAction="get"/>
      <wsdl:input name="methodRequest"/>
      <wsdl:output name="methodResponse"/>
    </wsdl:operation>

  </wsdl:binding>
</wsdl:definitions>

プロキシエンドポイントのプリフローに 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>
```

次の例に示すように、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 ペイロードをチェックするには:

プロキシエンドポイントのプリフローに SOAP Message Validation ポリシーを追加します。

ポリシー定義から <ResourceURL> 要素、<SOAPMessage> 要素、<Element> 要素を削除します。

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

<MessageValidation async="false" continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My JSON Checker</DisplayName>
  <Properties/>
  <Source>request</Source>
</MessageValidation>

次の例のように、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」

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 ステータス原因解決方法

障害コード	HTTP ステータス	原因
`steps.messagevalidation.SourceMessageNotAvailable`	500	このエラーは、ポリシーの `<Source>` 要素で指定された変数が次のいずれかである場合に発生します。範囲外（ポリシーが実行されている特定のフローで使用できない）または解決不能（未定義）
`steps.messagevalidation.NonMessageVariable`	500	このエラーは、SOAPMessageValidation ポリシーの `<Source>` 要素がメッセージ型以外の変数に設定されている場合に発生します。メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Edge フロー変数 `request`、`response`、`message` はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。
`steps.messagevalidation.Failed`	500	このエラーは、SOAPMessageValidation ポリシーが、XSD スキーマまたは WSDL 定義に対する入力メッセージペイロードを検証できなかった場合に発生します。また、ペイロードメッセージ内の JSON または XML の形式が正しくない場合にも発生します。

steps.messagevalidation.SourceMessageNotAvailable

500

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

範囲外（ポリシーが実行されている特定のフローで使用できない）
解決不能（未定義）

steps.messagevalidation.NonMessageVariable

500

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

メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Edge フロー変数 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 から入手できます。