JSONtoXML 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

此政策会将消息从 JavaScript 对象表示法 (JSON) 格式转换为可扩展标记语言 (XML)，并提供多个控制邮件转换方式的选项。

此政策特别适用于您想使用 XSL 转换消息的情况。将 JSON 载荷转换为 XML 后，在样式表中使用 XSL 转换政策来执行所需的转换。

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

注意：必须将来源消息的 HTTP Content-type 标头设置为 application/json，否则不会强制执行政策，意味着处理期间会跳过该政策。

假设意图是将 JSON 格式的请求转换为 XML 格式的请求，则政策将附加到请求流（例如，请求/ProxyEndpoint/PostFlow）。

示例

如需查看详细讨论，请参阅使用 Apigee 在 XML 和 JSON 之间进行转换：您需要了解的内容。

转换请求

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

此配置接受 JSON 格式的请求消息作为来源，然后创建在 request OutputVariable 中填充的 XML 格式消息。Apigee 会自动将此变量的内容用作下一个处理步骤的消息。

元素参考

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

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

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

属性	说明	默认	Presence
`name`	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
`continueOnError`	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障	false	可选
`enabled`	设置为 `true` 可强制执行政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
`async`	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

默认	不适用如果省略此元素，则会使用政策的 `name` 属性的值。
Presence	可选
类型	字符串

不适用

如果省略此元素，则会使用政策的 name 属性的值。

Presence 可选

类型字符串

<Source> 元素

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

注意：必须将来源消息的 HTTP Content-type 标头设置为 application/json，否则不会强制执行政策，意味着处理期间会跳过该政策。

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

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

<Source>request</Source>

默认	请求或响应，由将政策添加到 API 代理流的位置决定。
Presence	可选
类型	消息

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

<Options>/<OmitXmlDeclaration>

指定从输出中省略 XML 声明行。XML 声明行可以选择性地显示在 XML 文档的顶部。典型示例如下所示：

<?xml version="1.0" encoding="UTF-8"?>

在某些情况下，请务必避免在此政策的输出中包含此类行。一个好的示例是，您计划将此政策的输出作为片段嵌入较大的 XML 文档中。由于声明必须在文档中仅出现一次，并且仅在文档顶部显示，因此在这种情况下，在 XML 片段中禁止 XML 声明行非常重要。

此选项的默认值为 false，这意味着政策会在输出中包含 XML 声明行。以下设置会将政策配置为省略 XML 声明：

<OmitXmlDeclaration>true</OmitXmlDeclaration>

无法通过此政策的配置塑造或影响 XML 声明行的内容。该政策始终生成 UTF-8 编码文本并且始终使用 XML 1.0 版，声明语句（如果包含）将反映这一点。

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

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

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

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

架构

错误参考信息

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

运行时错误

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

故障代码	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`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

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

JSONtoXML 政策

内容

示例

转换请求

元素参考

<JSONToXML> 属性

<DisplayName> 元素

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

使用说明

架构

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

相关主题

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

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

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