JSONtoXML 政策

您正在查看 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

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

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

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

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 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 內容類型標頭會設為 text/xml;charset=UTF-8

如未指定 OutputVariable,系統會將 source 視為 OutputVariable。舉例來說,如果 sourcerequest,則 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) 無效或格式錯誤。
steps.jsontoxml.InCompatibleTypes 500 如果 <Source> 元素中定義的變數類型與 <OutputVariable> 元素不同,就會發生這個錯誤。請務必指定 <Source> 元素中包含的變數類型,且 <OutputVariable> 元素必須相符。有效的類型包括 messagestring
steps.jsontoxml.InvalidSourceType 500 如果用於定義 <Source> 元素的變數類型無效,就會發生這個錯誤。有效的變數類型為 messagestring
steps.jsontoxml.OutputVariableIsNotAvailable 500 如果 JSON 至 XML 政策的 <Source> 元素中指定的變數為類型字串,且 <OutputVariable> 元素未定義,就會發生這個錯誤。如果 <Source> 元素中定義的變數為類型字串,則 <OutputVariable> 元素為必要元素。
steps.jsontoxml.SourceUnavailable 500 從 JSON 至 XML 政策的 <Source> 元素中,如果指定 message 變數,就會發生這個錯誤:
  • 超出範圍 (不適用於執行政策的特定流程) 或
  • 無法解析 (未定義)

部署錯誤

無。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

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

相關主題