FormsMessageValidation 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

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

您可以使用 Message Validation 政策來驗證 XML 訊息要求的酬載 與 XSD 結構定義比較。

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

您可使用 Message Validation 政策來驗證 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> 會指定 <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

您可以使用 Message Validation 政策來確認 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>

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然名稱。

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

預設值 不適用
是否必填？ 選用設定。如果您省略 <DisplayName>， 使用政策的 name 屬性
類型 字串
父項元素 &lt;PolicyElement&gt;
子元素 無

<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 &quot;http://sample.com&quot; 選用 定義待驗證元素的命名空間。

<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> 的值必須指向資源 檔案。無法透過 HTTP 或 HTTPS 參照外部資源。

如果您沒有指定 <ResourceURL> 的值，系統會檢查訊息，找出格式正確的 JSON 如果 Content-type 標頭為「application/json」則會傳回 XML或「application/xml」 。

<ResourceURL> 元素不含任何子元素或屬性。

使用 XSD 進行驗證

若您使用 Message Validation 政策參照驗證的 XML 酬載 「另一個」結構定義，那麼您必須在內含的 XSD 檔案前面加上 xsd， schemaLocation 屬性。

以下結構定義範例包含多個 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 必須定義至少一個結構定義。如果沒有參照至少一個結構定義， Message Validation 政策失敗。

結構定義的最大匯入深度為 10。如果巢狀匯入數量超過這個上限， Message Validation 政策失敗。

<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>，這項政策會預設為「訊息」，也就是 要求訊息 (在要求流程中) 或回應訊息 (在回應流程中)，包括 酬載。您也可以明確將其設為「request」或「response」參考要求 回應。

預設值 申請。
是否必填？ 選用
類型 字串
父項元素 <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 提供許多資源。

相關主題