本頁面由 Cloud Translation API 翻譯而成。

FormsMessageValidation 政策

您正在查看 Apigee Edge 說明文件。
請參閱 Apigee X 說明文件。 info

SOAPMessageValidation 政策會執行下列操作：

驗證任何 XML 訊息是否符合 XSD 結構定義
根據 WSDL 定義驗證 SOAP 訊息
判斷 JSON 和 XML 訊息是否符合格式

雖然這項政策在使用者介面中的名稱為「SOAP 訊息驗證」，但政策驗證的項目不只限於 SOAP 訊息。本節將這項政策稱為「訊息驗證政策」。

關於「訊息驗證」政策

優點

訊息驗證有以下優點：

如果使用者要求不符合規定或不完整，系統會立即通知使用 API 的應用程式開發人員。
找出要求中的錯誤，例如未正確關閉的 XML 標記。
保護後端服務，封鎖含有可能導致行為不穩定的結構的 XML 或 SOAP 訊息。
縮短解決問題、搜尋論壇或諮詢技術支援所需的時間。
鼓勵開發人員熟悉 XML 架構 WSDL 定義，以消除驗證錯誤，並將易於理解的 XML 架構做為 API 說明文件的重要元素。

影片

請觀看下列影片，進一步瞭解「訊息驗證」政策：

影片	說明
驗證 XML 要求	使用「訊息驗證」政策驗證 API 的 XML 要求。
驗證 JSON 要求	使用「訊息驗證」政策驗證 API 的 JSON 要求。

`<MessageValidation>` 元素

定義「訊息驗證」政策。

預設值	請參閱下方的「Default Policy」分頁
是否必要？	選用
類型	複雜物件
上層元素	n/a
子元素	`<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 中，將訊息驗證政策新增至流程時的預設設定：

<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 訊息驗證政策新增至 Proxy 端點的預流程：

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

將 POST 要求傳送至 API 代理程，並將 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 驗證

您可以使用「訊息驗證」政策，驗證 SOAP 訊息要求的酬載是否符合 WSDL。

建立新的 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 訊息驗證政策新增至 Proxy 端點的預流程：

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

將 POST 要求傳送至 API Proxy，並使用 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 酬載是否格式正確，請按照下列步驟操作：

將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程。

從政策定義中移除 <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> 的值，系統會檢查訊息是否為正確格式的 JSON 或 XML，前提是 Content-type 標頭分別為「application/json」或「application/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」，以便參照要求或回應。

預設值	申請。
是否必要？	選用
類型	字串
上層元素	`<MessageValidation>`
子元素	無

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

語法

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

範例

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

除了「message」、「request」和「response」之外，您也可以將 <Source> 的值設為流程中任何訊息的名稱。不過，如果您採取這項做法，則必須在政策執行前，先在流程中建立具有該名稱的自訂訊息。否則會收到錯誤訊息。

如果在訊息流程中無法解析 <Source> 的值，或解析為非訊息類型，就會發生下列任一情況：

如果是空值：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 查看政策架構。

FormsMessageValidation 政策

關於「訊息驗證」政策

優點

影片

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