![](https://docs.apigee.com/static/api-platform/images/icon_policy_mediation.jpg?authuser=0&hl=ja)
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>
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 Optionally, use the |
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. |
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. |
例
次の例はそれぞれ、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 ポリシーを追加します。
<ResourceURL>
要素を使用して、XSD リソース ファイルの場所を指定します。例:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- ポリシー定義から
<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」)。
- プロキシ エンドポイントのプリフローに SOAP Message Validation ポリシーを追加します。
<SOAPMessage>
要素のversion
属性を、検証する SOAP プロトコルのバージョンに設定します。例: 1:1... <SOAPMessage version="1.1"/> ...
<Element>
要素の値を検証する要素に設定します。... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
は、SOAP リクエストのエンベロープの<Body>
要素の下にある最初の子を指定します。namespace
属性をその子の名前空間に設定します。<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>
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, more natural-sounding name.
The <DisplayName>
element is common to all policies.
Default Value | n/a |
Required? | Optional. If you omit <DisplayName> , the value of the
policy's name attribute is used |
Type | String |
Parent Element | <PolicyElement> |
Child Elements | None |
The <DisplayName>
element uses the following syntax:
Syntax
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
Example
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
The <DisplayName>
element has no attributes or child elements.
<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 バージョン。 有効な値は次のとおりです。
|
詳しくは、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 ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
This error occurs if a variable specified in the
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
This error occurs if the Message type variables represent entire HTTP requests and responses. The built-in Edge
flow variables |
build |
steps.messagevalidation.Failed |
500 | This error occurs if the SOAPMessageValidation policy fails to validate the input message payload against the XSD schema or WSDL definition. It will also occur if there is malformed JSON or XML in the payload message. | build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
InvalidResourceType |
The <ResourceURL> element in the SOAPMessageValidation policy is set to a resource type
not supported by the policy.
|
build |
ResourceCompileFailed |
The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation
policy contains an error that prevents it from compiling.
|
build |
RootElementNameUnspecified |
The <Element> element in the SOAPMessageValidation policy does not contain the root
element's name. |
build |
InvalidRootElementName |
The <Element> element in the SOAPMessageValidation policy contains a root element name
that does not adhere to XML rules for valid element naming. |
build |
スキーマ
各ポリシータイプは XML スキーマ(.xsd
)によって定義されます。ポリシー スキーマは GitHub から入手できます。