FormsMessageValidation 政策

標準政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

SOAPMessageValidation 政策會執行下列作業:

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

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

訊息驗證有以下好處:

  • 立即通知使用您 API 的應用程式開發人員,他們的請求是否不符規定或不完整。
  • 找出要求中的問題,例如未正確關閉的 XML 標記。
  • 保護後端服務:封鎖結構可能導致無法預測行為的 XML 或 SOAP 訊息。
  • 減少時間:不必再花時間排解問題、搜尋論壇或諮詢技術支援。
  • 鼓勵開發人員熟悉 XML 結構定義 WSDL,以消除驗證錯誤,讓 XML 結構定義成為 API 說明文件的重要組成部分。

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

影片

如要進一步瞭解 MessageValidation 政策,請觀看下列影片:

影片 說明
驗證 XML 要求 使用 MessageValidation 政策驗證 API 的 XML 要求。
驗證 JSON 要求 使用 MessageValidation 政策驗證 API 的 JSON 要求。

<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. 在 Proxy 端點的預先流程中新增 SOAP 訊息驗證政策:
    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. 將 SOAP 信封做為訊息酬載,傳送 POST 要求至 API Proxy,如下列範例所示:
    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>

除了 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 Proxy 中的資源檔案。無法透過 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 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 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 格式,也会发生此错误。

部署错误

在您部署包含此政策的代理时,可能会发生这些错误。

错误名称 原因 修复
InvalidResourceType SOAPMessageValidation 政策中的 <ResourceURL> 元素被设置为该政策不支持的资源类型。
ResourceCompileFailed SOAPMessageValidation 政策的 <ResourceURL> 元素中引用的资源脚本包含错误,导致其无法编译。
RootElementNameUnspecified SOAPMessageValidation 政策中的 <Element> 元素不包含根元素的名称。
InvalidRootElementName SOAPMessageValidation 政策中的 <Element> 元素包含的根元素名称未遵循有效元素命名的 XML 规则。

結構定義

每個政策類型都由 XML 結構定義 (.xsd)。如需參考,請前往 GitHub 查看政策結構定義。

相關主題