JSONtoXML 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

此政策会将消息从 JavaScript 对象表示法 (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="jsont>oxml&<quot;
>    Sou<rcerequ>est/S<ource
    Outp>utVaria<blerequest/Outp>u<tVariable
>/JSONToXML

此配置接受 JSON 格式的请求消息作为来源，然后创建在 request OutputVariable 中填充的 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

N/A

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

<Source> 元素

包含要转换为 XML 的 JSON 消息的变量、请求或响应。

如果未定义 <Source>，则系统会将其视为消息（当政策附加到请求流时解析为请求，或者在政策附加到响应流时响应）。

如果源变量无法解析或解析为非消息类型，则政策会提示错误。

<Source>request</Source>
默认 请求或响应，由将政策添加到 API 代理流的位置决定。
状态 可选
Type 消息

<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 代理流的位置决定。
状态 如果 <Source> 元素中定义的变量为字符串类型，则此元素是必填的。
Type 消息

<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/>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 值。默认情况下，值为 NULL。

例如，以下设置：

<NullValue>I_AM_NULL</NullValue>
 转换以下 JSON 对象： 
{"person" : &quot;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 政策通常与出站响应流上的 XMLtoJSON 政策配对。通过以这种方式合并政策，您可以针对原生仅支持 XML 的服务公开 JSON API。

将默认（空）JSON 应用于 XML 政策并根据需要以迭代方式添加配置元素通常会很有帮助。

对于可能需要 JSON 和 XML 的多种客户端应用使用 API 的情况，系统可以通过将 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 到 XML 政策 的 <Source> 元素中指定的变量为字符串类型，且未定义 <OutputVariable> 元素，则会发生此错误。如果 <Source> 元素中定义的变量为字符串类型，则 <OutputVariable> 元素是必填的。
steps.jsontoxml.SourceUnavailable 500 如果 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>

相关主题