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="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

元素参考

下面是您可以在此政策中配置的元素和属性。

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

下表介绍了所有政策父元素通用的特性：

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

<Source> 元素

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

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

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

<Source>request</Source>

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

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

例如，以下设置：

<NullValue>I_AM_NULL</NullValue>

{"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 政策通常与出站响应流上的 XMLtoJSON 政策配对。通过以这种方式合并政策，您可以针对原生仅支持 XML 的服务公开 JSON API。

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

对于可能需要 JSON 和 XML 的多种客户端应用使用 API 的情况，系统可以通过将 JSON 到 XML 和 XML 到 JSON 政策配置为有条件执行，动态设置响应的格式。如需了解此使用场景的实现情况，请参阅流变量和条件。

架构

错误参考信息

本部分介绍此政策触发错误时返回的错误代码和错误消息，以及 Edge 设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

无。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

错误响应示例

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

相关主题

• XML 到 JSON：XML to JSON 政策
• XSL 转换：XSL Transform 政策