您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
這項政策會將 JavaScript Object Notation (JSON) 格式的訊息轉換為可擴充的標記語言 (XML),並且提供多種選項,讓你控制訊息的轉換方式。
如果您要使用 XSL 轉換郵件,這項政策特別實用。將 JSON 酬載轉換為 XML 後,請搭配自訂樣式表使用 XSL 轉換政策,執行您需要的轉換。
假設意圖是將 JSON 格式要求轉換為 XML 格式要求,該政策會附加至要求流程,例如要求 / ProxyEndpoint/PostFlow。
範例
有關如何在 JSON 和 XML 之間轉換的詳細討論,請參閱 http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html。
轉換要求
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
這項設定會以 JSON 格式要求訊息做為來源,然後建立 XML 格式的訊息,並在 request
OutputVariable 中填入。Edge 會自動使用這個變數的內容做為下一個處理步驟的訊息。
元素參照
以下是您可以為這項政策設定的元素和屬性。
<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1"> <DisplayName>JSON to XML 1</DisplayName> <Source>request</Source> <OutputVariable>request</OutputVariable> <Options> <OmitXmlDeclaration>false</OmitXmlDeclaration> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator> <AttributeBlockName>#attrs</AttributeBlockName> <AttributePrefix>@</AttributePrefix> <ObjectRootElementName>Root</ObjectRootElementName> <ArrayRootElementName>Array</ArrayRootElementName> <ArrayItemElementName>Item</ArrayItemElementName> <Indent>false</Indent> <TextNodeName>#text</TextNodeName> <NullValue>I_AM_NULL</NullValue> <InvalidCharsReplacement>_</InvalidCharsReplacement> </Options> </JSONToXML>
<JSONToXML> 屬性
下表說明所有政策父項元素的通用屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<Source> 元素
變數、要求或回應,其中包含要轉換為 XML 的 JSON 訊息。
如未定義 <Source>
,系統會將其視為訊息 (在將政策附加至要求流程時解析要求,或是將政策附加至回應流程的回應)。
如果來源變數無法解析,或解析為非訊息類型,政策會擲回錯誤。
<Source>request</Source>
預設 | 要求或回應 (取決於政策新增至 API Proxy 流程的位置) |
外觀狀態 | 選用 |
類型 | 訊息 |
<OutputVariable> 元素
儲存 JSON 為 XML 格式轉換的輸出內容。這通常與來源的值相同,也就是 JSON 要求通常會轉換為 XML 要求。
系統會剖析 JSON 訊息的酬載並轉換為 XML,且 XML 格式訊息的 HTTP 內容類型標頭會設為 text/xml;charset=UTF-8
。
如未指定 OutputVariable
,系統會將 source
視為 OutputVariable
。舉例來說,如果 source
是 request
,則 OutputVariable
的預設值為 request
。
<OutputVariable>request</OutputVariable>
預設 | 要求或回應 (取決於政策新增至 API Proxy 流程的位置) |
外觀狀態 | 如果 <Source> 元素中定義的變數屬於類型字串,就必須使用這個元素。 |
類型 | 訊息 |
<選項>/<OmitXmlDeclaration>
指定在輸出內容中省略 XML 命名空間。預設值為 false
,表示輸出內容中會包含命名空間。
例如,下列設定將政策設為省略命名空間:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
<Options>/<命名空間 BlockName>
<Options>/<Default 命名空間 NodeName>
<Options>/<命名空間 Separator> 元素
JSON 不支援命名空間,而 XML 文件通常需要這些命名空間。
NamespaceBlockName
可讓您定義 JSON 屬性,做為政策產生的 XML 中的命名空間定義來源。(這表示來源 JSON 必須提供一項屬性,且該屬性可對應至使用產生的 XML 的應用程式預期的命名空間。
例如下列設定:
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator>
表示來源 JSON 中存在名為 #namespaces
的屬性,該屬性包含至少一個指定為預設的命名空間。例如:
{ "population": { "#namespaces": { "$default": "http://www.w3.org/1999/people", "exp": "http://www.w3.org/1999/explorers" }, "person": "John Smith", "exp:person": "Pedro Cabral" } }
會轉換為:
<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers"> <person>John Smith</person> <exp:person>Pedro Cabral</exp:person> </population>
<Options>/<ObjectRootElementName>
<ObjectRootElementName> 可指定您在從 JSON 轉換為 XML 時 (不含已命名的根元素) 的根元素名稱。
例如,如果 JSON 顯示如下:
{ "abc": "123", "efg": "234" }
然後將 <ObjectRootElementName> 設為:
<ObjectRootElementName>Root</ObjectRootElementName>
產生的 XML 會顯示為:
<Root> <abc>123</abc> <efg>234</efg> </Root>
<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> 元素
<AttributeBlockName>
可讓您指定 JSON 元素轉換為 XML 屬性 (而非 XML 元素) 的時機。
舉例來說,下列設定會將 #attrs
物件內的屬性轉換為 XML 屬性:
<AttributeBlockName>#attrs</AttributeBlockName>
下列 JSON 物件:
{ "person" : { "#attrs" : { "firstName" : "John", "lastName" : "Smith" }, "occupation" : "explorer", } }
轉換為下列 XML 結構:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<AttributePrefix>
會將開頭為指定前置字串的屬性轉換為 XML 屬性。其中屬性前置字元已設為 @
,例如:
<AttributePrefix>@</AttributePrefix>
轉換下列 JSON 物件:
{ "person" : { "@firstName" : "John", "@lastName" : "Smith" "occupation" : "explorer", } }
對應至以下 XML 結構:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> 元素
將 JSON 陣列轉換為含有指定父項和子項元素名稱的 XML 元素清單。
例如下列設定:
<ArrayRootElementName>Array</ArrayRootElementName> <ArrayItemElementName>Item</ArrayItemElementName>
轉換下列 JSON 陣列:
[ "John Cabot", { "explorer": "Pedro Cabral" }, "John Smith" ]
轉換為以下 XML 結構:
<Array> <Item>John Cabot</Item> <Item> <explorer>Pedro Cabral</explorer> </Item> <Item>John Smith</Item> </Array>
<選項>/<縮排>
指定 XML 輸出縮排。預設值為 false
,表示不縮排。
舉例來說,下列設定可將政策設為縮排:
<Indent>true</Indent>
如果 JSON 輸入內容的格式為:
{"n": [1, 2, 3] }
接著輸出不含縮排的輸出內容:
<Array><n>1</n><n>2</n><n>3</n></Array>
啟用縮排後,輸出結果如下:
<Array> <n>1</n> <n>2</n> <n>3</n> </Array>
<Options>/<TextNodeName> 元素
將 JSON 屬性轉換為具有指定名稱的 XML 文字節點。例如,使用下列設定:
<TextNodeName>age</TextNodeName>
會轉換下列 JSON:
{ "person": { "firstName": "John", "lastName": "Smith", "age": 25 } }
加入以下 XML 結構:
<person> <firstName>John</firstName>25<lastName>Smith</lastName> </person>
如未指定 TextNodeName
,系統會使用文字節點的預設設定產生 XML:
<person> <firstName>John</firstName> <age>25</age> <lastName>Smith</lastName> </person>
<Options>/<NullValue> 元素
表示空值。預設值為 NULL
。
以下列設定為例:
<NullValue>I_AM_NULL</NullValue>轉換下列 JSON 物件:
{"person" : "I_AM_NULL"}
以下 XML 元素:
<person></person>
如果未指定空值 (或 I_AM_NULL
以外的值),則相同的酬載會轉換為:
<person>I_AM_NULL</person>
<Options>/<InvalidCharsReplacement> 元素
為協助處理可能導致剖析器發生問題的無效 XML,這項設定會將產生無效 XML 的所有 JSON 元素替換為字串。以下列設定為例:
<InvalidCharsReplacement>_</InvalidCharsReplacement>
轉換這個 JSON 物件
{ "First%%%Name": "John" }
加入以下 XML 結構:
<First_Name>John<First_Name>
使用須知
在一般的中介服務情境中,傳入要求流程的 JSON 到 XML 政策通常會與傳出回應流程的 XML 到 JSON 政策配對。以這種方式合併政策,就能針對只支援 XML 的服務公開 JSON API。
將預設 (空白) JSON 套用至 XML 政策,並視需求疊代新增設定元素通常很有用。
如果各種用戶端應用程式使用 API (可能需要 JSON 和 XML),您可以將 JSON 設為 XML 和 XML,以有條件的方式執行 JSON 政策,藉此動態設定回應的格式。如要實作此情境,請參閱流程變數和條件。
結構定義
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 | 輸入酬載 (JSON) 為空白,或是傳遞至 JSON 政策的輸入 (JSON) 無效或格式錯誤。 | build |
steps.jsontoxml.InCompatibleTypes |
500 | 如果 <Source> 元素中定義的變數類型與 <OutputVariable> 元素不同,就會發生這個錯誤。請務必指定 <Source> 元素中包含的變數類型,且 <OutputVariable> 元素必須相符。有效的類型包括 message 和 string 。 |
build |
steps.jsontoxml.InvalidSourceType |
500 | 如果用於定義 <Source> 元素的變數類型無效,就會發生這個錯誤。有效的變數類型為 message 和 string 。 |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 | 如果 JSON 至 XML 政策的 <Source> 元素中指定的變數為類型字串,且 <OutputVariable> 元素未定義,就會發生這個錯誤。如果 <Source> 元素中定義的變數為類型字串,則 <OutputVariable> 元素為必要元素。 |
build |
steps.jsontoxml.SourceUnavailable |
500 |
從 JSON 至 XML 政策的 <Source> 元素中,如果指定 message 變數,就會發生這個錯誤:
|
build |
部署錯誤
無。
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "fault": { "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available", "detail": { "errorcode": "steps.json2xml.SourceUnavailable" } } }
故障規則示例
<FaultRule name="JSON To XML Faults"> <Step> <Name>AM-SourceUnavailableMessage</Name> <Condition>(fault.name Matches "SourceUnavailable") </Condition> </Step> <Step> <Name>AM-BadJSON</Name> <Condition>(fault.name = "ExecutionFailed")</Condition> </Step> <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition> </FaultRule>
相關主題
- XML 到 JSON:從 XML 到 JSON 政策
- XSL 轉換:XSL 轉換政策