SOAPMessageValidation 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

SOAPMessageValidation 政策会执行以下操作：

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

虽然界面中的政策名称是 SOAPMessageValidation，但该政策不仅仅用来验证 SOAP 消息。本部分将该政策称为 MessageValidation 政策。

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

<MessageValidation> 元素

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

默认政策

以下示例显示了在 Apigee 界面中向您的流添加 MessageValidation 政策时的默认设置：

<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> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError 否 可选 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：
enabled true 可选 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async   否 已弃用 此属性已弃用。

示例

以下示例展示了使用 MessageValidation 政策的一些方法：

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. 使用 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 消息请求的载荷。

  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. 将 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 载荷的格式是否正确，请执行以下操作：

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

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

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

<SOAPMessage>

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

默认值 request
是否必需？ 可选
类型 字符串
父元素 <MessageValidation>
子元素 无

<Source> 元素使用以下语法：

语法

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

示例

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

除了 message、request 和 response 之外，您还可以将 <Source> 的值设置为流中任何消息的名称。但是，如果您执行此操作，则必须在执行该政策之前在您的流中创建具有该名称的自定义消息。否则，您将会收到错误。

如果无法在消息流中解析 <Source> 的值或解析为非消息类型，则会出现以下任一情况：

  • 如果值为 null：Apigee 会抛出 steps.messagevalidation.SourceMessageNotAvailable 错误。
  • 如果是非消息类型：则 Apigee 会抛出 steps.messagevalidation.NonMessageVariable 错误。

<Source> 元素没有特性或子元素。

错误代码

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.messagevalidation.SourceMessageNotAvailable 500

如果政策的 <Source> 元素中指定的变量为以下任一项，就会出现此错误：

  • 超出范围（在执行政策的特定流中不可用）
    • 或
  • 无法解析（未定义）
steps.messagevalidation.NonMessageVariable 500

如果将 SOAPMessageValidation 政策中的 <Source> 元素设为不是 Message 类型的变量，则会发生此错误。

消息类型变量表示整个 HTTP 请求和响应。内置 Apigee 流变量 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 提供了政策架构作为参考。

相关主题