JSONtoXML 政策

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

查看 Apigee Edge 說明文件。

結果

這項政策會將 JavaScript 物件標記法 (JSON) 格式的訊息轉換為可延伸標記語言 (XML)，並提供多種選項，讓您控管訊息的轉換方式。

如果您想使用 XSL 轉換訊息，這項政策就特別實用。將 JSON 酬載轉換為 XML 後，請使用 XSL 轉換政策和自訂樣式表，執行所需的轉換。

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

注意：來源訊息的 HTTP Content-type 標頭必須設為 application/json，否則系統不會強制執行政策，也就是在處理期間會略過該訊息。

假設意圖是將 JSON 格式的要求轉換為 XML 格式的要求，則政策會附加至要求流程 (例如 Request / ProxyEndpoint / PostFlow)。

範例

如需詳細討論，請參閱「 使用 Apigee 在 XML 與 JSON 之間進行轉換：您需要瞭解的事項」。

轉換要求

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

這項設定會以 JSON 格式的要求訊息做為來源，然後建立 XML 格式的訊息，並填入 request OutputVariable。Apigee 會自動將這個變數的內容做為訊息，用於下一個處理步驟。

---

元素參考資料

您可以在這項政策中設定下列元素和屬性。

<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	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設	不適用 如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性	選用
類型	字串

<Source> 元素

包含要轉換為 XML 的 JSON 訊息的變數、要求或回應。

注意：來源訊息的 HTTP Content-type 標頭必須設為 application/json，否則系統不會強制執行政策，也就是在處理期間會略過該訊息。

如果未定義 <Source>，系統會將其視為訊息 (當政策附加至要求流程時，會解析為要求；當政策附加至回應流程時，會解析為回應)。

如果無法解析來源變數，或解析為非訊息類型，政策就會擲回錯誤。

<Source>request</Source>

預設	要求或回應，取決於政策新增至 API Proxy 流程的位置
外觀狀態	選用
類型	訊息

<OutputVariable> 元素

儲存 JSON 轉 XML 格式的輸出內容。這通常與來源的值相同，也就是說，JSON 要求通常會轉換為 XML 要求。

系統會剖析 JSON 訊息的酬載並轉換為 XML，然後將 XML 格式訊息的 HTTP Content-type 標頭設為 text/xml;charset=UTF-8。

如未指定 OutputVariable，系統會將 source 視為 OutputVariable。舉例來說，如果 source 是 request，則 OutputVariable 預設為 request。

<OutputVariable>request</OutputVariable>

預設	要求或回應，取決於政策新增至 API Proxy 流程的位置
外觀狀態	如果 <Source> 元素中定義的變數屬於字串類型，就必須使用這個元素。
類型	訊息

<Options>/<OmitXmlDeclaration>

指定從輸出內容中省略 XML 宣告行。XML 宣告行可選擇性地顯示在 XML 文件頂端。常見的範例如下：

<?xml version="1.0" encoding="UTF-8"?>

在某些情況下，請務必避免在政策輸出內容中加入這類行。舉例來說，如果您打算將這項政策的輸出內容以片段形式嵌入較大的 XML 文件中，就是一個很好的例子。因為宣告在文件中只能出現一次，而且只能出現在文件頂端，因此在這種情況下，請務必在 XML 片段中隱藏 XML 宣告行。

這個選項的預設值為 false，表示政策會在輸出內容中加入 XML 宣告行。下列設定會將政策設為省略 XML 宣告：

<OmitXmlDeclaration>true</OmitXmlDeclaration>

您無法透過這項政策的設定，塑造或影響 XML 宣告行的內容。這項政策一律會產生 UTF-8 編碼的文字，並一律使用 XML 1.0 版，如果包含宣告行，也會反映這點。

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> 元素

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>

<Options>/<Indent>

指定要縮排 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>

如果未指定 Null 值 (或指定的值不是 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 政策，有條件地執行，動態設定回應格式。如要瞭解如何實作這個情境，請參閱「流程變數和條件」。

結構定義

範例：如要查看最新結構定義，請參閱 GitHub 存放區範例。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則來處理錯誤，就必須瞭解這項資訊。如需更多資訊，請參閱「 政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

提示：需要協助解決錯誤嗎？按一下「修正」欄中的 ，即可查看詳細的疑難排解資訊。

錯誤代碼	HTTP 狀態	原因	修正
steps.jsontoxml.ExecutionFailed	500	輸入酬載 (JSON) 為空白，或是傳遞至 JSON 至 XML 政策的輸入內容 (JSON) 無效或格式錯誤。
steps.jsontoxml.InCompatibleTypes	500	如果 <Source> 元素和 <OutputVariable> 元素中定義的變數類型不一致，就會發生這項錯誤。<Source> 元素和 <OutputVariable> 元素中包含的變數類型必須一致。有效的類型為 message 和 string。
steps.jsontoxml.InvalidSourceType	500	如果用來定義 <Source> 元素的變數類型無效，就會發生這個錯誤。有效的變數類型為 message 和 string。
steps.jsontoxml.OutputVariableIsNotAvailable	500	如果 JSON 至 XML 政策的 <Source> 元素中指定的變數為字串類型，且未定義 <OutputVariable> 元素，就會發生這項錯誤。如果 <Source> 元素中定義的變數為字串類型，則必須使用 <OutputVariable> 元素。
steps.jsontoxml.SourceUnavailable	500	如果 JSON 到 XML 政策的 <Source> 元素中指定的 message 變數為下列任一情況，就會發生此錯誤： 超出範圍 (無法在執行政策的特定流程中使用)，或 無法解析 (未定義)

部署錯誤

無

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
fault.name="fault_name"	fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。	fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed	policy_name 是擲回錯誤的政策的使用者指定名稱。	jsontoxml.JSON-to-XML-1.failed = true

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{
  "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：XMLtoJSON 政策。
• XSL 轉換：XSLTransform 政策