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

FormsMessageValidation 政策

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

SOAPMessageValidation 政策會執行下列作業：

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

雖然這項政策在使用者介面中的名稱是「SOAP 訊息驗證」，但政策驗證的內容不只 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>`

除了 name 屬性，您也可以使用這個屬性，在管理 UI 代理程式編輯器中，以更自然易懂的名稱標示政策。

所有政策都有 <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」

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 政策傳回的錯誤會採用一致的格式，詳情請參閱「錯誤代碼參考資料」。

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤代碼 HTTP 狀態原因修正

錯誤代碼	HTTP 狀態	原因
`steps.messagevalidation.SourceMessageNotAvailable`	500	如果政策的 `<Source>` 元素中有指定變數，就會發生這個錯誤：超出範圍 (不適用於執行政策的特定流程) 或無法解析 (未定義)
`steps.messagevalidation.NonMessageVariable`	500	如果 SOAPMessageValidation 政策中的 `<Source>` 元素設為不屬於 message 類型的變數，就會發生這個錯誤。訊息類型變數代表整個 HTTP 要求和回應。內建 Edge 流程變數 `request`、`response` 和 `message` 屬於訊息類型。如要進一步瞭解訊息變數，請參閱「變數參考資料」。
`steps.messagevalidation.Failed`	500	如果 SOAPMessageValidation 政策無法針對 XSD 結構定義或 WSDL 定義驗證輸入訊息酬載，就會發生這個錯誤。如果酬載訊息中有格式錯誤的 JSON 或 XML，也會發生這種狀況。

steps.messagevalidation.SourceMessageNotAvailable

500

如果政策的 <Source> 元素中有指定變數，就會發生這個錯誤：

超出範圍 (不適用於執行政策的特定流程)
無法解析 (未定義)

steps.messagevalidation.NonMessageVariable

500

如果 SOAPMessageValidation 政策中的 <Source> 元素設為不屬於 message 類型的變數，就會發生這個錯誤。

訊息類型變數代表整個 HTTP 要求和回應。內建 Edge 流程變數 request、response 和 message 屬於訊息類型。如要進一步瞭解訊息變數，請參閱「變數參考資料」。

steps.messagevalidation.Failed 500 如果 SOAPMessageValidation 政策無法針對 XSD 結構定義或 WSDL 定義驗證輸入訊息酬載，就會發生這個錯誤。如果酬載訊息中有格式錯誤的 JSON 或 XML，也會發生這種狀況。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤名稱	原因	修正
`InvalidResourceType`	SOAPMessageValidation 政策中的 `<ResourceURL>` 元素會設為政策不支援的資源類型。
`ResourceCompileFailed`	在 SOAPMessageValidation 政策的 `<ResourceURL>` 元素中參照的資源指令碼中，有一項錯誤導致無法編譯。
`RootElementNameUnspecified`	SOAPMessageValidation 政策中的 `<Element>` 元素不含根元素的名稱。
`InvalidRootElementName`	SOAPMessageValidation 政策中的 `<Element>` 元素包含的根元素名稱不符合 XML 規則的有效元素命名規則。

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

FormsMessageValidation 政策

關於訊息驗證政策

優點

影片

<MessageValidation> 元素

語法

預設政策

範例

1：XSD 驗證

2：SOAP 驗證

3：格式正確的 XML/JSON

子元素參照

<DisplayName>

語法

範例

<Element>

語法

範例 1

範例 2

<ResourceURL>

語法

範例

使用 XSD 進行驗證

使用 WSDL 進行驗證

<SOAPMessage>

語法

範例

<Source>

語法

範例

錯誤代碼

執行階段錯誤

部署錯誤

結構定義

相關主題

`<MessageValidation>` 元素

`<DisplayName>`

`<Element>`

`<ResourceURL>`

`<SOAPMessage>`

`<Source>`