FormsMessageValidation 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

SOAPMessageValidation 政策會執行下列操作：

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

雖然這項政策在 UI 中的名稱為 SOAPMessageValidation，但這項政策驗證的項目不只 SOAP 訊息。本節將這項政策稱為「MessageValidation」政策。

這項政策是標準政策，可部署至任何環境類型。如要瞭解政策類型和各環境類型的可用性，請參閱「政策類型」。

<MessageValidation> 元素

定義 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>

預設政策

以下範例顯示在 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 驗證

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

  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. 向 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>

除了 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> 元素沒有屬性或子項元素。

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因 修正
steps.messagevalidation.SourceMessageNotAvailable 500

如果政策的 <Source> 元素中指定的變數為下列任一情況，就會發生此錯誤：

  • 超出範圍 (在執行政策的特定流程中不可用)
    • 或
  • 無法解析 (未定義)
steps.messagevalidation.NonMessageVariable 500

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

訊息類型變數代表整個 HTTP 要求和回應。內建的 Apigee 流程變數 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 查看政策架構。

相關主題