FormsMessageValidation 政策

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊

SOAPMessageValidation 政策會執行下列作業：

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

雖然這項政策在 UI 中的名稱為「SOAP Message Validation」，但政策不只驗證 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. 使用 XML 做為訊息酬載，將 POST 要求傳送至 API Proxy，如以下範例所示： 
    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 Proxy，如以下範例所示： 
    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>

在管理 UI Proxy 編輯器中，除了 name 屬性，可用以其他自然更自然的名稱為政策加上標籤。

<DisplayName> 元素適用於所有政策。

預設值 n/a
是否必填？ 選用設定。如果省略 <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 Proxy 中的資源檔案。無法經由 HTTP 或 HTTPS 參照外部資源。

如果您未指定 <ResourceURL> 的值，如果 Content-type 標頭是「application/json」或「application/xml」，系統會檢查訊息的 JSON 或 XML 格式是否正確。

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

使用 XSD 進行驗證

如果您使用訊息驗證政策驗證的 XML 酬載參照「其他」結構定義，則您必須在內含的 XSD 檔案 schemaLocation 屬性中加上 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 版本。

預設值 n/a
是否必填？ 選用
類型 n/a
父項元素 <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>，這項政策會預設為「訊息」，也就是在要求流程中參照的完整要求訊息或回應訊息 (在回應流程中)，包括任何酬載。您也可以明確將其設為「要求」或「回應」，以便參照要求或回應。

預設值 申請。
是否必填？ 選用
類型 字串
父項元素 <MessageValidation>
子元素 無

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

語法

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

範例

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

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

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

  • 如果值為空值：邊緣會擲回 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 查看政策結構定義。

相關主題