FormsMessageValidation 政策

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

SOAPMessageValidation 政策會執行下列作業：

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

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

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

此元素在所有政策中皆包含下列屬性：

屬性 預設 必填與否 Description
name 無 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個字元。

或者，您也可以使用 <DisplayName> 元素，在管理 UI Proxy 編輯器中，以不同的自然語言名稱來標示政策。
continueOnError false 選填 如果設為「false」，當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」，則在政策失敗後，仍會繼續執行流程。
enabled true 選填 設為「true」即可強制執行政策。將政策設為「false」，即可「關閉」政策。即使政策已附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 這項屬性已淘汰。

範例

以下範例說明如何使用「訊息驗證」政策：

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> 的值，如果 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」

詳情請參閱「從 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 狀態 原因 修正
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 查看政策架構。

相關主題