SOAPMessageValidation 政策

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 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。
async   已弃用 此属性已弃用。

示例

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

1:XSD 验证

// [START common_links] // [END common_links] // [START flow_variables] // [END flow_variables] // [START main_body] // [END main_body] // [START proxy_config_ref] // [END proxy_config_ref] // [START environment_variables] // [END environment_variables] // [START tooltips] // [END tooltips] // [START apis] // [END apis]

您可以使用消息验证政策针对 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 验证

// [START common_links] // [END common_links] // [START flow_variables] // [END flow_variables] // [START main_body] // [END main_body] // [START proxy_config_ref] // [END proxy_config_ref] // [START environment_variables] // [END environment_variables] // [START tooltips] // [END tooltips] // [START apis] // [END apis]

您可以使用消息验证政策针对 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

// [START common_links] // [END common_links] // [START flow_variables] // [END flow_variables] // [START main_body] // [END main_body] // [START proxy_config_ref] // [END proxy_config_ref] // [START environment_variables] // [END environment_variables] // [START tooltips] // [END tooltips] // [START apis] // [END apis]

您可以使用消息验证政策来确认 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>

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/jsonapplication/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,指的是完整的请求消息(在请求流中)或响应消息(在响应流程中),包括任何载荷。您也可以将它明确设置为 requestresponse,以指代请求或响应。

默认值 请求
是否必需? 可选
类型 字符串
父元素 <MessageValidation>
子元素

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

语法

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

示例

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

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

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

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

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

错误代码

Apigee 政策返回的错误采用一致的格式,如政策参考中所述。

架构

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

相关主题