JSONtoXML 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

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

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

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

假設意圖是將 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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

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

<Source> 元素

變數、要求或回應，其中包含要轉換為 XML 的 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>

如果沒有為空值指定任何值 (或 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 政策，以條件式執行方式動態設定回應格式。如要瞭解如何實作此情境，請參閱「流程變數和條件」。

結構定義

錯誤參考資料

本節說明這項政策觸發錯誤時，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

錯誤回應範例

{
  "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>

相關主題