SOAPMessageValidation 政策

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

SOAPMessageValidation 政策会执行以下操作:

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

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

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

此元素具有所有政策中常见的以下属性:

属性 默认 是否必需? 说明
name N/A 必需

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

continueOnError false 可选 设置为“false” 可在政策失败时返回错误。这是大多数政策的预期行为。如果设置为“true”,则即使政策失败,仍可继续执行流。
enabled 可选 设为“true”可强制执行政策。设为“false”可“关闭”政策。即使政策仍附加到某个流,也不会强制执行该政策。
async   false 已弃用 此属性已弃用。

示例

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

1:XSD 验证

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

  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 消息验证政策添加到代理端点的预流中:
    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. 向 API 代理发送 POST 请求,并将 XML 作为消息载荷,如以下示例所示:
    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 消息请求的载荷。

  1. 创建一个新的 WSDL 资源文件。例如,“example-wsdl.wsdl”:
  2. 将 SOAP 消息验证政策添加到代理端点的预流中:
    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. 向 API 代理发送 POST 请求,并将 SOAP 信封作为消息载荷,如以下示例所示:
    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 载荷的格式是否正确,请执行以下操作:

  1. 将 SOAP 消息验证政策添加到代理端点的预流中。
  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 属性之外,还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<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> 元素来指定要验证的多个元素:

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

如需了解详情,请参阅从 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 值: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
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.

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 提供了政策架构作为参考。

相关主题