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

結構定義

錯誤參考資料

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.jsontoxml.ExecutionFailed 500 The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes 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. The valid types are message and string.
steps.jsontoxml.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.
steps.jsontoxml.OutputVariableIsNotAvailable 500 This error occurs if the variable specified in the <Source> element of the JSON to XML 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.
steps.jsontoxml.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either:
  • out of scope (not available in the specific flow where the policy is being executed) or
  • can't be resolved (is not defined)

Deployment errors

None.

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 Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. jsontoxml.JSON-to-XML-1.failed = true

Example error response

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

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

相關主題