JSONtoXML 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

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

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

範例

如要詳細瞭解如何轉換 JSON 和 XML，請參閱「回應物件中的 JSON 陣列轉換為 XML 陣列的問題」。

轉換要求

<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

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<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 命名空間。預設值為 false，表示輸出內容中包含命名空間。

舉例來說，下列設定會將政策設為省略命名空間：

<OmitXmlDeclaration>true</OmitXmlDeclaration>

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

結構定義

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

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

錯誤程式碼 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 的 <Source> 元素中指定的變數指向以下清單，就會發生這個錯誤： XML 政策是類型字串，且未定義 <OutputVariable> 元素。 如果在 <Source> 中定義的變數，則 <OutputVariable> 是必要元素 元素屬於類型字串。
steps.jsontoxml.SourceUnavailable 500 如果系統傳回這個錯誤，表示 message 而在 JSON 到 XML 政策的 <Source> 元素中指定的是以下任一變數：
  • 超出範圍 (不適用於執行政策的特定流程)
  • 無法解析 (未定義)

部署錯誤

無。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。

變數 地點 範例
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>

相關主題