FormsMessageValidation 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

SOAPMessageValidation 政策會執行下列作業：

根據 XSD 架構驗證任何 XML 訊息
根據 WSDL 定義驗證 SOAP 訊息
判斷 JSON 和 XML 訊息是否格式正確

雖然這項政策在 UI 中的名稱是「SOAP Message Validation」，但政策驗證的內容不只 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 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 驗證

您可以使用「訊息驗證」政策，根據 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 訊息驗證政策新增至 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>

如下列範例所示，傳送 POST 要求至 API 代理：

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」，以參照要求或回應。

預設值	申請。
必填與否	選用
類型	字串
父項元素	`<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>`