本頁面由 Cloud Translation API 翻譯而成。

JSONtoXML 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

結果

這項政策會將 JavaScript Object Notation (JSON) 格式的訊息轉換為可延伸格式標記語言 (XML)，提供數種控制郵件轉換方式的選項。

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

注意：您必須設定來源郵件的 HTTP Content-type 標頭設為 application/json，否則系統不會強制執行這項政策，系統會略過這個流程。

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

範例

如需在 JSON 和 XML 之間轉換的詳細討論，請參閱 http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html。

轉換要求

<JSONToXML name="jsont>oxml&<quot;
>    Sou<rcerequ>est/S<ource
    Outp>utVaria<blerequest/Outp>u<tVariable
>/JSONToXML

這項設定會將 JSON 格式的要求訊息做為來源，然後再建立填入 request 輸出變數中的 XML 格式訊息。邊緣會自動使用這個變數的內容，做為下一個處理步驟的訊息。

元素參照

以下是您可以為這項政策設定的元素和屬性。

<JSONToXML async="false" continueOnError="false" enabled="t>rue&q<uot; name=&>quot;JSON-to-<XML-1"<>/span>
    D<isplay>NameJSO<N to XM>L 1/D<isplayName
   > Source<request/Source
>    O<utputVa>riablereq<uest/OutputVariabl>e
   < Options
        Om>itXmlDecl<arationfalse/OmitXmlDecl>aration
<        DefaultNamespaceN>odeName$d<efault/DefaultName>s<paceNodeName
      >  Namespa<ceSeparator:/Names>paceSe<parator
        Att>ributeBlo<ckName#attrs/At>t<ributeBlockName<>/span>
        A<ttributePrefix@/Attri>bute<Prefix
        ObjectR>ootElemen<tNameRoot/ObjectRoot>Eleme<ntName
        ArrayR>ootElemen<tNameArray/ArrayRoot>Elem<entName
        Array>ItemEleme<ntName>Item/<ArrayIt>emElement<Name
       > Inde<ntfalse/Inden>t
       < TextNode>Name#text</TextNodeN>ame
     <   NullValueI_AM_NULL/N>u<llValue
        InvalidC>harsR<eplaceme>n<t_/Invalid>CharsReplacement
    /Options
/JSONToXML

<JSONToXML>屬性

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
`name`	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
`continueOnError`	Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails.	false	Optional
`enabled`	Set to `true` to enforce the policy. Set to `false` to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
`async`	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default

Default	N/A If you omit this element, the value of the policy's `name` attribute is used.
Presence	Optional
Type	String

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional

Type String

<Source>元素

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

注意：您必須設定來源郵件的 HTTP Content-type 標頭設為 application/json，否則系統不會強制執行這項政策，表示系統會略過該政策。

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

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

<Source>request</Source>

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

<OutputVariable>元素

儲存 JSON 的輸出格式轉換為 XML 格式。這個值通常會與來源，通常會將 JSON 要求轉換為 XML 要求。

剖析 JSON 訊息的酬載並轉換為 XML，以及 HTTP Content-type XML 格式訊息的標頭已設為 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 屬性，做為命名空間的來源定義。(這表示來源 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/>199<9/expl>orers"<;
  per>son<John Smith>/person
  ex<p:personPed>r<o Cabral/ex>p: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" lastNa>me=<"Smit>h"
<  occupatio>n<explore>r/occupation
/person

<AttributePrefix> 會轉換開頭為指定前置字串的屬性轉換為 XML 屬性屬性前置字元設為 @，例如：

<AttributePrefix>@</AttributePrefix>

轉換下列 JSON 物件：

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

新增至以下 XML 結構：

<person firstName="John" lastNa>me=<"Smit>h"
<  occupatio>n<explore>r/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" : &quot;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 政策通常會是並比對傳出回應流程中的 XMLtoJSON 政策。以這種方式結合政策可以為原生支援 XML 的服務公開 JSON API。

將預設的 (空白) JSON 套用至 XML 政策，並反覆新增所需設定元素

適用於不同用戶端應用程式可能需以 JSON 格式使用 API 的情況和 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
`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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

JSONtoXML 政策

結果

範例

轉換要求

元素參照

&lt;JSONToXML&gt;屬性

<DisplayName> element

&lt;Source&gt;元素

&lt;OutputVariable&gt;元素

&lt;Options&gt;/&lt;OmitXmlDeclaration&gt;

&lt;Options&gt;/&lt;NamespaceBlockName&gt; &lt;Options&gt;/&lt;DefaultNamespaceNodeName&gt; &lt;Options&gt;/&lt;NamespaceSeparator&gt;個元素

&lt;Options&gt;/&lt;ObjectRootElementName&gt;

&lt;Options&gt;/&lt;AttributeBlockName&gt; &lt;Options&gt;/&lt;AttributePrefix&gt;個元素

&lt;Options&gt;/&lt;ArrayRootElementName&gt; &lt;Options&gt;/&lt;ArrayItemElementName&gt;元素

&lt;Options&gt;/&lt;Indent&gt;

&lt;Options&gt;/&lt;TextNodeName&gt;元素

&lt;Options&gt;/&lt;NullValue&gt;元素

&lt;Options&gt;/&lt;InvalidCharsReplacement&gt;元素

使用須知

結構定義

錯誤參考資料

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

相關主題

<JSONToXML>屬性

<Source>元素

<OutputVariable>元素

<Options>/<OmitXmlDeclaration>

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

<Options>/<ObjectRootElementName>

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix>個元素

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName>元素

<Options>/<Indent>

<Options>/<TextNodeName>元素

<Options>/<NullValue>元素

<Options>/<InvalidCharsReplacement>元素