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

結果
這項政策會將可延伸標記語言 (XML) 格式的郵件轉換成 JavaScript Object Notation (JSON),提供數種控制訊息的方式 已產生轉換
假設意圖是將 XML 格式的回應轉換為 JSON 格式 回應,政策會附加至回應流程 (例如:Response / ProxyEndpoint) / PostFlow。
關於
在一般中介服務的情況下,傳入請求流程中的 JSON 到 XML 政策通常會是 並在傳出回應流程中與 XML 對 JSON 政策配對。以這種方式結合政策 您可以針對原生僅支援 XML 的後端服務公開 JSON API。
適合需要以 JSON 或 XML,則可將 JSON 設為 XML,並將 XML 設為 JSON,以動態方式設定回應格式 以便有條件地執行請參閱流程變數和條件。 實作這個情境
範例
如需在 JSON 和 XML 之間轉換的詳細討論,請參閱 http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html。
轉換回應
<XMLToJSON name="ConvertToJSON"> <Options> </Options> <OutputVariable>response</OutputVariable> <Source>response</Source> </XMLToJSON>
這項設定 — 將 XML 轉換為
JSON:先將 XML 格式的回應訊息當做來源,然後
填入 response
輸出變數中的 JSON 格式訊息。邊緣
會自動使用這個變數的內容,做為下一個處理步驟的訊息。
元素參照
以下是您可以為這項政策設定的元素和屬性。
<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1"> <DisplayName>XML to JSON 1</DisplayName> <Source>response</Source> <OutputVariable>response</OutputVariable> <Options> <RecognizeNumber>true</RecognizeNumber> <RecognizeBoolean>true</RecognizeBoolean> <RecognizeNull>true</RecognizeNull> <NullValue>NULL</NullValue> <NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName> <NamespaceSeparator>***</NamespaceSeparator> <TextAlwaysAsProperty>true</TextAlwaysAsProperty> <TextNodeName>TEXT</TextNodeName> <AttributeBlockName>FOO_BLOCK</AttributeBlockName> <AttributePrefix>BAR_</AttributePrefix> <OutputPrefix>PREFIX_</OutputPrefix> <OutputSuffix>_SUFFIX</OutputSuffix> <StripLevels>2</StripLevels> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options> <!-- Use Options or Format, not both --> <Format>yahoo</Format> </XMLToJSON>
<XMLtoJSON>屬性
<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
下表說明所有政策父項元素的共同屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 視需要使用 |
不適用 | 必填 |
continueOnError |
如果設為「 如果設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName>元素
除 name
屬性外,一併使用
管理 UI Proxy 編輯器,使用不同的自然語言名稱。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<Source>元素
變數、要求或回應,包含您要轉換的 XML 訊息。 JSON 檔案。
來源郵件的 HTTP Content-type 標頭必須設為
application/xml
,否則系統不會強制執行這項政策。
如未定義 <Source>
,系統會將其視為訊息 (
政策附加至要求流程時的要求,或在附加政策時回應
回應流程)。
如果無法解析來源變數,或是無法解析為非訊息類型,就會顯示政策 擲回錯誤。
<Source>response</Source>
預設 | 要求或回應,取決於將政策新增至 API Proxy 流程的位置 |
外觀狀態 | 選用 |
類型 | 訊息 |
<OutputVariable>元素
將 XML 的輸出內容儲存成 JSON 格式。這個值通常會與 來源,通常會將 XML 回應轉換為 JSON 回應。
剖析 XML 訊息的酬載並轉換為 JSON,以及 HTTP Content-type
XML 格式訊息的標頭已設為 application/json
。
如未指定 OutputVariable
,系統會將 source
視為
OutputVariable
。舉例來說,如果 source
是 response
,
OutputVariable
則預設為 response
。
<OutputVariable>response</OutputVariable>
預設 | 要求或回應,取決於將政策新增至 API Proxy 流程的位置 |
外觀狀態 | 如果 <Source> 元素中定義的變數是類型字串,就必須強制使用這個元素。 |
類型 | 訊息 |
<Options>
這些選項可讓您控制從 XML 到 JSON 的轉換。請使用
<Options>
群組:可讓您新增特定轉換設定,或是
<Format>
元素,可讓您參照
預先定義的選項您無法同時使用 <Options>
和
<Format>
。
如果您沒有使用 <Format>
,就必須提供 <Options>
。
<Options>/<RecognizeNumber>元素
如果為 true,XML 酬載中的數字欄位會保留原始格式。
<RecognizeNumber>true</RecognizeNumber>
請參考以下 XML 範例:
<a> <b>100</b> <c>value</c> </a>
如果是 true
,則會轉換為:
{ "a": { "b": 100, "c": "value" } }
如果是 false
,則會轉換為:
{ "a": { "b": "100", "c": "value" } }
預設 | false |
外觀狀態 | 選用 |
類型 | 布林值 |
<Options>/<RecognizeBoolean>元素
讓轉換保持布林值 true/false 值,而非將值轉換為 字串。
<RecognizeBoolean>true</RecognizeBoolean>
針對以下 XML 範例:
<a> <b>true</b> <c>value</c> </a>
如果是 true
,則會轉換為:
{ "a": { "b": true, "c": "value" } }
如果是 false
,則會轉換為:
{ "a": { "b": "true", "c": "value" } }
預設 | false |
外觀狀態 | 選用 |
類型 | 布林值 |
<Options>/<RecognizeNull>元素
可讓您將空白值轉換為空值。
<RecognizeNull>true</RecognizeNull>
針對以下 XML:
<a> <b></b> <c>value</c> </a>
如果是 true
,則會轉換為:
{ "a": { "b": null, "c": "value" } }
如果是 false
,則會轉換為:
{ "a": { "b": {}, "c": "value" } }
預設 | false |
外觀狀態 | 選用 |
類型 | 布林值 |
<Options>/<NullValue>元素
表示來源訊息中應辨識為空值的值
已產生轉換預設值為 null
。這個選項只適用於
如果 RecognizeNull
為 true。
<NullValue>not-present</NullValue>
預設 | null |
外觀狀態 | 選用 |
類型 | 字串 |
<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>個元素
請同時使用下列元素。
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName> <NamespaceSeparator>***</NamespaceSeparator>
請參考以下 XML 範例:
<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com"> <ns1:b>value</ns1:b> </a>
如果未指定 NamespaceSeparator
,則下列 JSON 結構為
已產生:
{ "a": { "b": "value" } }
如果元素 NamespaceBlockName
、DefaultNamespaceNodeName
和
NamespaceSeparator
指定為 #namespaces
、&
、
和 ***
,隨後會產生下列 JSON 結構:
{ "a": { "#namespaces": { "&": "http://ns.com", "ns1": "http://ns1.com" }, "ns1***b": "value" } }
預設 | 請參閱上方的範例。 |
外觀狀態 | 選填 不過,如果指定 <NamespaceBlockName> ,就必須同時指定
其他兩個元素 |
類型 | 字串 |
<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>個元素
請同時使用下列元素。
如果設為 true
,則 XML 元素的內容會轉換為字串
資源。
<TextAlwaysAsProperty>true</TextAlwaysAsProperty> <TextNodeName>TEXT</TextNodeName>
針對以下 XML:
<a> <b>value1</b> <c>value2<d>value3</d>value4</c> </a>
如果 TextAlwaysAsProperty
設為 true
和 TextNodeName
指定為 TEXT
,則會產生下列 JSON 結構:
{ "a": { "b": { "TEXT": "value1" }, "c": { "TEXT": [ "value2", "value4" ], "d": { "TEXT": "value3" } } } }
如果 TextAlwaysAsProperty
設為 false
,且
將 TextNodeName
指定為 TEXT
,下列 JSON 結構為
已產生:
{ "a": { "b": "value1", "c": { "TEXT": [ "value2", "value4" ], { "d": "value3", } } }
預設 | <TextAlwaysAsProperty> :false<TextNodeName> :不適用 |
外觀狀態 | 選用 |
類型 | <TextAlwaysAsProperty> :布林值<TextNodeName> :字串 |
<Options>/<AttributeBlockName>
<Options>/<AttributePrefix>個元素
請同時使用下列元素。
可讓您將值歸入 JSON 區塊,並在屬性名稱後方加上前置字元。
<AttributeBlockName>FOO_BLOCK</AttributeBlockName> <AttributePrefix>BAR_</AttributePrefix>
請參考以下 XML 範例:
<a attrib1="value1" attrib2="value2"/>
如果屬性 (AttributeBlockName
和 AttributePrefix
) 都為
並產生下列 JSON 結構 (如 XML 至 JSON 範例所定義):
{ "a": { "FOO_BLOCK": { "BAR_attrib1": "value1", "BAR_attrib2": "value2" } } }
如果僅指定 AttributeBlockName
,則下列 JSON 結構為
已產生:
{ "a": { "FOO_BLOCK": { "attrib1": "value1", "attrib2": "value2" } } }
如果僅指定 AttributePrefix
,則下列 JSON 結構為
已產生:
{ "a": { "BAR_attrib1": "value1", "BAR_attrib2": "value2" } }
如果兩者皆未指定,系統會產生下列 JSON 結構:
{ "a": { "attrib1": "value1", "attrib2": "value2" } }
預設 | 請參閱上方的範例。 |
外觀狀態 | 選用 |
類型 | 字串 |
<Options>/<OutputPrefix>
<Options>/<OutputSuffix>個元素
請同時使用下列元素。
<OutputPrefix>PREFIX_</OutputPrefix> <OutputSuffix>_SUFFIX</OutputSuffix>
請參考以下 XML 範例:
<a>value</a>
如果同時指定 OutputPrefix
和 OutputSuffix
屬性
如從 XML 到 JSON 範例所定義,會產生下列 JSON 結構:
PREFIX_{ "a": "value" }_SUFFIX
如果僅指定 OutputPrefix
,會產生下列 JSON 結構:
PREFIX_{ "a" : "value" }
如果僅指定 OutputSuffix
,會產生下列 JSON 結構:
{ "a" : "value" }_SUFFIX
如果 OutputPrefix
和 OutputSuffix
皆未指定,則下列情況:
系統會產生 JSON 結構:
{ "a": "value" }
預設 | 請參閱上方範例。 |
外觀狀態 | 選用 |
類型 | 字串 |
<Options>/<StripLevels>元素
<Options> <StripLevels>4</StripLevels> </Options>
有時候,SOAP 等 XML 有效負載 (例如 SOAP) 中會包含您不希望包含在 經過轉換的 JSON 檔案以下是包含多個層級的 SOAP 回應範例:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/"> <GetCityWeatherByZIPResult> <State>CO</State> <City>Denver</City> <Description>Sunny</Description> <Temperature>62</Temperature> </GetCityWeatherByZIPResult> </GetCityWeatherByZIPResponse> </soap:Body> </soap:Envelope>
進入「州/省」、「城市」、「說明」和「溫度」等級之前,共有 4 個等級。
如果沒有使用 <StripLevels>
,轉換後的 JSON 回應會如下所示
:
{ "Envelope" : { "Body" : { "GetCityWeatherByZIPResponse" : { "GetCityWeatherByZIPResult" : { "State" : "CO", "City" : "Denver", "Description" : "Sunny", "Temperature" : "62" } } } } }
如要去除 JSON 回應中的前 4 個層級,請
<StripLevels>4</StripLevels>
,以利您取得下列資訊
JSON:
{ "State" : "CO", "City" : "Denver", "Description" : "Sunny", "Temperature" : "62" }
您可以去除層級,直到第一個包含多個子項的元素為止。用途 是什麼意思?接著來看看更複雜的 JSON 範例:
{ "Envelope" : { "Body" : { "GetCityForecastByZIPResponse" : { "GetCityForecastByZIPResult" : { "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
這個範例中的第 3 級是 GetCityForecastByZIPResponse
,這個示例只有一個
孩子。因此,如果您使用 <StripLevels>3</StripLevels>
(請將
前三個層級),JSON 應如下所示:
{ "GetCityForecastByZIPResult" : { "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
請注意,GetCityForecastByZIPResult
有多個子項。由於這是
第一個包含多個子項的元素時,您可以使用「
<StripLevels>4</StripLevels>
,您將收到以下項目
JSON:
{ "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
由於第 4 級是含有多個子項的第一個層,因此您無法排除任何等級 低於這個金額如果將條紋層級設為 5、6、7 等,即可繼續取得 回應。
預設 | 0 (無層級去除) |
外觀狀態 | 選用 |
類型 | 整數 |
<Options>/<TreatAsArray>/<Path>元素
<Options> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
這種元素組合可確保 XML 文件的值採用 JSON
陣列。舉例來說,當子元素的數量可能不一時 (從 1 到 1)
而您想要確保陣列中的值一律位於陣列中。這麼做可以確保
程式碼穩定,因為您每次都可以相同的方式從陣列取得資料。適用對象
範例:$.teachers.teacher.studentnames[0]
會取得首位學生姓名值
陣列的值,無論陣列中的值數量為何。
讓我們先回顧一下從 XML 到 JSON 的預設行為,並探索如何
使用 <TreatAsArray>/<Path>
控制輸出內容。
XML 文件內含包含多個子值的元素 (通常是根據結構定義)
元素的 maxOccurs='unbounded'
) 時,系統會自動將 XML 到 JSON 政策提供給使用者
將這些值放到陣列中例如,下列 XML 區塊
<teacher> <name>teacherA</name> <studentnames> <name>student1</name> <name>student2</name> </studentnames> </teacher>
...在不具有特殊政策的情況下,會自動轉換為下列 JSON 格式 設定:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]} } } }
請注意,兩個學生姓名會放入陣列中。
不過,如果 XML 文件中只有一位學生,則會自動套用 XML 到 JSON 政策 會將該值視為單一字串,而非字串陣列,如下所示 範例:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : "student1" } } } }
在前例中,類似的資料是以陣列的形式完成轉換,
單一字串。這就是 <TreatAsArray>/<Path>
元素
就能控制輸出內容舉例來說,您可以一律輸入學生姓名
陣列。設定方法是找出
元素,如下所示:
<Options> <TreatAsArray> <Path>teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
上述設定會寫入 JSON,如下所示:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : ["student1"] } ] } } }
請注意,學生 1 現在位於陣列中。現在,無論您有多個
學生可以使用以下 JSONPath,從程式碼中的 JSON 陣列擷取這些學生:
$.teachers.teacher.studentnames.name[0]
<Path>
元素也具有 unwrap
屬性,詳細說明如下:
請參閱下一節的說明。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
屬性
<Options> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
屬性 | 說明 | 存在必要性 | 類型 |
---|---|---|---|
解除包裝 |
預設值:false 從 JSON 輸出中移除元素。請使用這個資料欄簡化或簡化 (「解除包裝」)
也會縮短擷取值所需的 JSONPath。例如:
而不是 以下是 JSON 範例: { "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]}... 在這個範例中,您可以參照 <TreatAsArray> <Path unwrap="true">teachers/teacher</Path> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray>
{ "teachers" : [{ "name" : "teacherA", "studentnames" : ["student1","student2"] }]... 請注意,由於 |
選用 | 布林值 |
如需更多範例和功能逐步操作說明,請參閱這篇 Apigee 社群文章:https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html。
<Format>
您可運用格式,掌控從 XML 轉換為 JSON 的過程。輸入預先定義參數的名稱
範本,其中包含本主題所述的選項元素組合。
預先定義的格式包括:xml.com
、yahoo
、google
、
badgerFish
。
使用 <Format>
元素或 <Options>
群組。您無法使用
<Format>
和 <Options>
。
以下是各個預先定義範本的格式定義。
xml.com
<RecognizeNull>true</RecognizeNull> <TextNodeName>#text</TextNodeName> <AttributePrefix>@</AttributePrefix>
yahoo
<RecognizeNumber>true</RecognizeNumber> <TextNodeName>content</TextNodeName>
<TextNodeName>$t</TextNodeName> <NamespaceSeparator>$</NamespaceSeparator> <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
badgerFish
<TextNodeName>$</TextNodeName> <TextAlwaysAsProperty>true</TextAlwaysAsProperty> <AttributePrefix>@</AttributePrefix> <NamespaceSeparator>:</NamespaceSeparator> <NamespaceBlockName>@xmlns</NamespaceBlockName> <DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>
元素語法:
<Format>yahoo</Format>
預設 | 輸入可用格式的名稱:xml.com 、yahoo 、google 、badgerFish |
外觀狀態 | 如果您沒有使用 <Options> ,則為必要欄位。 |
類型 | 字串 |
結構定義
錯誤參考資料
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.xmltojson.ExecutionFailed |
500 | This error occurs when the input payload (XML) is empty or the input XML is invalid or malformed. | build |
steps.xmltojson.InCompatibleType |
500 | This error occurs if the type of the variable defined in the <Source> element and the
<OutputVariable> element are not the same. It is mandatory that the type of the variables
contained within the <Source> element and the <OutputVariable> element matches.
|
build |
steps.xmltojson.InvalidSourceType |
500 | This error occurs if the type of the variable used to define the <Source> element is
invalid.The valid types of variable are message and string. |
build |
steps.xmltojson.OutputVariableIsNotAvailable |
500 | This error occurs if the variable specified in the <Source> element of the XML to
JSON policy is of type string and the <OutputVariable> element is not defined.
The <OutputVariable> element is mandatory when the variable defined in the <Source>
element is of type string. |
build |
steps.xmltojson.SourceUnavailable |
500 |
This error occurs if the message
variable specified in the <Source> element of the XML to JSON policy is either:
|
build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
EitherOptionOrFormat |
If one of the elements <Options> or <Format> is not
declared in the XML to JSON Policy, then the deployment of the API proxy fails.
|
build |
UnknownFormat |
If the <Format> element within the XML to JSON policy has an unknown
format defined, then the deployment of the API proxy fails. Predefined formats include:
xml.com , yahoo , google , and badgerFish .
|
build |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name = "SourceUnavailable" |
xmltojson.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | xmltojson.XMLtoJSON-1.failed = true |
Example error response
{ "fault": { "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available", "detail": { "errorcode": "steps.xml2json.SourceUnavailable" } } }
Example fault rule
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults"> <Step> <Name>AM-SourceUnavailableMessage</Name> <Condition>(fault.name Matches "SourceUnavailable") </Condition> </Step> <Step> <Name>AM-BadXML</Name> <Condition>(fault.name = "ExecutionFailed")</Condition> </Step> <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition> </FaultRule>
相關主題
JSON 到 XML:JSON 到 XML 政策