此页面由 Cloud Translation API 翻译。

SOAPMessageValidation 政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

SOAPMessageValidation 政策会执行以下操作：

针对相应的 XSD 架构验证 XML 消息
针对 WSDL 定义验证 SOAP 消息
确定 JSON 和 XML 消息格式的正确性

虽然此政策在界面中的名称是“SOAP 消息验证”，但其验证的不仅仅是 SOAP 消息。在本部分中，此政策是指“消息验证政策”。

消息验证政策简介

优势

消息验证具有以下优势：

如果使用您的 API 的应用开发者的请求不符合规则或不完整，立即通知他们。
查明请求中的问题，如未正确关闭的 XML 标记。
通过阻止具有可能导致不可预见行为的结构的 XML 或 SOAP 消息，来保护后端服务。
减少在排查问题、搜索论坛或咨询技术支持团队方面花费的时间。
鼓励开发者熟悉 XML 架构 WSDL 定义以消除验证错误，从而使那些易于理解的 XML 架构成为 API 文档的一个重要组成部分。

视频

观看以下视频，详细了解消息验证政策：

视频	说明
验证 XML 请求	使用消息验证政策验证 API 的 XML 请求。
验证 JSON 请求	使用消息验证政策验证 API 的 JSON 请求。

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

默认政策

以下示例显示了在 Edge 界面中向您的流添加消息验证政策时的默认设置：

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

示例

以下示例展示了使用消息验证政策的一些方法：

1：XSD 验证

您可以使用消息验证政策针对 XSD 架构来验证 XML 消息请求的载荷。

创建一个新的 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 消息验证政策添加到代理端点的预流中：

使用 <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 验证

您可以使用消息验证政策针对 WSDL 来验证 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 消息验证政策添加到代理端点的预流中：

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

您可以使用消息验证政策来确认 JSON 或 XML 消息载荷的格式正确（不同于验证）。该政策可确保结构和内容符合接受的标准，包括：

有一个根元素
内容中没有非法字符
对象和标记已正确嵌套
开始标记和结束标记相一致

如需检查 XML 或 JSON 载荷的格式是否正确，请执行以下操作：

将 SOAP 消息验证政策添加到代理端点的预流中。

从政策定义中移除 <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> 元素来指定要验证的多个元素：

...
<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 进行验证

如果您使用消息验证政策验证的 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 必须至少定义一个架构。如果它未引用至少一个架构，则消息验证政策将会失败。

架构的最大导入深度为 10。如果超出嵌套导入数，则消息验证政策将失败。

`<SOAPMessage>`

定义消息验证政策针对其进行验证的 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”，以指代请求或响应。

默认值	request
是否必需？	可选
类型	字符串
父元素	`<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 政策返回的错误采用一致的格式，如错误代码参考中所述。

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

Fault code	HTTP status	Cause
`steps.messagevalidation.SourceMessageNotAvailable`	500	This error occurs if a variable specified in the `<Source>` element of the policy is either: out of scope (not available in the specific flow where the policy is being executed) or can't be resolved (is not defined)
`steps.messagevalidation.NonMessageVariable`	500	This error occurs if the `<Source>` element in the SOAPMessageValidation policy is set to a variable which is not of type message. Message type variables represent entire HTTP requests and responses. The built-in Edge flow variables `request`, `response`, and `message` are of type message. To learn more about message variables, see the Variables reference.
`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.

steps.messagevalidation.SourceMessageNotAvailable

500

This error occurs if a variable specified in the <Source> element of the policy is either:

out of scope (not available in the specific flow where the policy is being executed)
can't be resolved (is not defined)

steps.messagevalidation.NonMessageVariable

500

This error occurs if the <Source> element in the SOAPMessageValidation policy is set to a variable which is not of type message.

Message type variables represent entire HTTP requests and responses. The built-in Edge flow variables request, response, and message are of type message. To learn more about message variables, see the Variables reference.

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.

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.
`ResourceCompileFailed`	The resource script referenced in the `<ResourceURL>` element of the SOAPMessageValidation policy contains an error that prevents it from compiling.
`RootElementNameUnspecified`	The `<Element>` element in the SOAPMessageValidation policy does not contain the root element's name.
`InvalidRootElementName`	The `<Element>` element in the SOAPMessageValidation policy contains a root element name that does not adhere to XML rules for valid element naming.

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

SOAPMessageValidation 政策

消息验证政策简介

优势

视频

<MessageValidation> 元素

语法

默认政策

示例

1：XSD 验证

2：SOAP 验证

3：格式正确的 XML/JSON

子元素参考

<DisplayName>

Syntax

Example

<Element>

语法

示例 1

示例 2

<ResourceURL>

语法

示例

使用 XSD 进行验证

使用 WSDL 进行验证

<SOAPMessage>

语法

示例

<Source>

语法

示例

错误代码

Runtime errors

Deployment errors

架构

相关主题

`<MessageValidation>` 元素

`<DisplayName>`

`<Element>`

`<ResourceURL>`

`<SOAPMessage>`

`<Source>`