FormsMessageValidation 政策

本頁內容適用於 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 UI 中將 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> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
enabled 是 選用 設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 此屬性已淘汰。

範例

下列範例說明如何使用 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 訊息驗證政策新增至 Proxy 端點的預先流程：
    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. 將 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 訊息要求的酬載。

  1. 建立新的 WSDL 資源檔案。 例如「example-wsdl.wsdl」：
  2. 將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程：
    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. 將 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 酬載格式是否正確：

  1. 將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程。
  2. 從政策定義中移除 <ResourceURL>、<SOAPMessage> 和 <Element> 元素。

    您的政策定義應如下所示：

    <MessageValidation async="false" continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My JSON Checker</DisplayName>
  <Properties/>
  <Source>request</Source>
</MessageValidation>
  3. 如下列範例所示，傳送 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> 的值，系統會檢查訊息是否為格式正確的 JSON 或 XML，前提是 Content-type 標頭分別為 application/json 或 application/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，以參照要求或回應。

預設值 要求
必填與否 選用
類型 字串
父項元素 <MessageValidation>
子元素 無

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

語法

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

範例

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

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

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

  • 如果是空值：Apigee 會擲回 steps.messagevalidation.SourceMessageNotAvailable 錯誤。
  • 如果不是訊息類型：Apigee 會擲回 steps.messagevalidation.NonMessageVariable 錯誤。

<Source> 元素沒有屬性或子項元素。

錯誤代碼

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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
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 Apigee 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 查看政策架構。

相關主題