查看 Apigee Edge 說明文件。
前往
Apigee X說明文件。 資訊
![](https://docs.apigee.com/static/api-platform/images/icon_policy_mediation.jpg?authuser=1&hl=zh-tw)
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 |
無 | 必要 |
政策的內部名稱。 或者,您也可以使用 |
continueOnError |
false | 選填 | 如果設為「false」,當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」,則在政策失敗後,仍會繼續執行流程。 |
enabled |
true | 選填 | 設為「true」即可強制執行政策。將政策設為「false」,即可「關閉」政策。即使政策已附加至流程,系統也不會強制執行這項政策。 |
async |
false | 已淘汰 | 這項屬性已淘汰。 |
範例
以下範例說明一些使用「訊息驗證」功能的方式 政策:
1:XSD 驗證
您可以使用 Message Validation 政策來驗證 XML 訊息要求的酬載 與 XSD 結構定義比較。
- 建立新的 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>
- 將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程:
- 使用
<ResourceURL>
指定 XSD 資源檔案的位置 元素。例如:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- 將
<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>
- 使用
- 以訊息形式使用 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。
- 建立新的 WSDL 資源檔案。 例如「example-wsdl.wsdl」:
- 將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程:
- 將
<SOAPMessage>
元素的version
屬性設為 要驗證的 SOAP 通訊協定版本。例如: 「1.1」:... <SOAPMessage version="1.1"/> ...
- 將
<Element>
元素的值設為所需元素 驗證:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
會指定<Body>
元素下的第一個子項 。將
namespace
屬性設為該子項的命名空間。 - 使用
<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>
- 將
- 將
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 酬載:
- 將 SOAP 訊息驗證政策新增至 Proxy 端點的預先流程中。
- 移除
<ResourceURL>
、<SOAPMessage>
。 和<Element>
政策定義中的元素。政策定義應如下所示:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- 將
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 屬性 |
類型 | 字串 |
父項元素 | <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>
的值必須指向資源
檔案。無法透過 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 版本。
有效值如下:
|
若需更多資訊,請參閲 從 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 |
如果政策的
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
如果 SOAPMessageValidation 政策中的 訊息類型變數代表整個 HTTP 要求和回應。內建 Edge 流程變數 |
build |
steps.messagevalidation.Failed |
500 | 如果 SOAPMessageValidation 政策無法針對 XSD 結構定義或 WSDL 定義驗證輸入訊息酬載,就會發生這個錯誤。如果酬載訊息中有格式錯誤的 JSON 或 XML,也會發生這種狀況。 | build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidResourceType |
SOAPMessageValidation 政策中的 <ResourceURL> 元素會設為政策不支援的資源類型。
|
build |
ResourceCompileFailed |
在 SOAPMessageValidation 政策的 <ResourceURL> 元素中參照的資源指令碼中,有一項錯誤導致無法編譯。
|
build |
RootElementNameUnspecified |
SOAPMessageValidation 政策中的 <Element> 元素不含根元素的名稱。 |
build |
InvalidRootElementName |
SOAPMessageValidation 政策中的 <Element> 元素包含的根元素名稱不符合 XML 規則的有效元素命名規則。 |
build |
結構定義
每種政策類型都是由 XML 架構 (.xsd
) 定義。供參考政策結構定義
GitHub 提供許多資源。