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

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

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

状态可选

类型字符串

<Source> 元素

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

注意：必须将来源消息的 HTTP Content-type 标头设置为 application/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 声明行。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 政策配置为有条件执行，动态设置响应的格式。如需了解此使用场景的实现情况，请参阅流变量和条件。

架构

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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 政策

内容

示例

转换请求

元素参考

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

使用说明

架构

错误参考信息

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

相关主题

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

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

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