Política JSONtoXML

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

La política JSONtoXML convierte los mensajes del formato de notación de objetos JavaScript (JSON) al lenguaje de marcado extensible (XML), lo que le ofrece varias opciones para controlar cómo se convierten los mensajes.

Esta política es especialmente útil si quieres transformar mensajes mediante XSL. Después de convertir una carga útil JSON en XML, usa la política de transformación XSL con una hoja de estilo personalizada para realizar la transformación que necesites.

Si el objetivo es convertir una solicitud con formato JSON en una solicitud con formato XML, la política se adjuntaría a un flujo de solicitud (por ejemplo, Request/ProxyEndpoint/PostFlow).

Esta política es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad de cada tipo de entorno, consulta Tipos de políticas.

Ejemplos

Para obtener información detallada, consulta el artículo Converting between XML and JSON with Apigee: what you need to know (Convertir entre XML y JSON con Apigee: lo que debes saber).

Convertir una solicitud

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

Esta configuración toma como origen un mensaje de solicitud con formato JSON y, a continuación, crea un mensaje con formato XML que se rellena en request OutputVariable. Apigee usa automáticamente el contenido de esta variable como mensaje para el siguiente paso de procesamiento.

Referencia de elemento

A continuación, se indican los elementos y atributos que puede configurar en esta política.

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

Atributos de <JSONToXML>

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Atributo Descripción Predeterminado Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

Elemento <Source>

La variable, solicitud o respuesta que contiene el mensaje JSON que quieres convertir a XML.

Si no se define <Source>, se trata como un mensaje (que se resuelve como una solicitud cuando la política se adjunta a un flujo de solicitudes o como una respuesta cuando la política se adjunta a un flujo de respuestas).

Si no se puede resolver la variable de origen o se resuelve en un tipo que no es de mensaje, la política genera un error.

<Source>request</Source>
Predeterminado solicitud o respuesta, en función de dónde se añada la política al flujo del proxy de la API
Presencia Opcional
Tipo mensaje

Elemento <OutputVariable>

Almacena el resultado de la conversión del formato JSON a XML. Normalmente, es el mismo valor que el de la fuente, es decir, una solicitud JSON se convierte en una solicitud XML.

La carga útil del mensaje JSON se analiza y se convierte en XML, y el encabezado Content-type de HTTP del mensaje con formato XML se define como text/xml;charset=UTF-8.

Si no se especifica OutputVariable, source se trata como OutputVariable. Por ejemplo, si source es request, OutputVariable tendrá el valor predeterminado request.

<OutputVariable>request</OutputVariable>
Predeterminado solicitud o respuesta, en función de dónde se añada la política al flujo del proxy de la API
Presencia Este elemento es obligatorio cuando la variable definida en el elemento <Source> es de tipo cadena.
Tipo mensaje

<Options>/<OmitXmlDeclaration>

Especifica que se omita la línea de declaración XML de la salida. Una línea de declaración XML puede aparecer de forma opcional en la parte superior de un documento XML. Un ejemplo habitual sería el siguiente: 

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

En algunos casos, es importante evitar incluir esta línea en el resultado de esta política. Un buen ejemplo es si tiene previsto insertar el resultado de esta política como un fragmento en un documento XML más grande. Como la declaración solo puede aparecer una vez en un documento y solo en la parte superior del documento, en ese caso sería importante suprimir la línea de declaración XML en el fragmento XML.

El valor predeterminado de esta opción es false, lo que significa que la política incluirá la línea de declaración XML en el resultado. El siguiente ajuste configurará la política para omitir la declaración XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

No se puede dar forma ni afectar al contenido de la línea de declaración XML mediante la configuración de esta política. La política siempre genera texto codificado en UTF-8 y siempre usa la versión 1.0 de XML. Si se incluye la línea de declaración, se reflejará en ella.

Elementos <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

JSON no admite espacios de nombres, mientras que los documentos XML suelen necesitarlos. NamespaceBlockName te permite definir una propiedad JSON que sirve como fuente de una definición de espacio de nombres en el XML que genera la política. Esto significa que el JSON de origen debe proporcionar una propiedad que se pueda asignar a un espacio de nombres que espere la aplicación que consuma el XML resultante.

Por ejemplo, los siguientes ajustes:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

indica que existe una propiedad llamada #namespaces en el JSON de origen que contiene al menos un espacio de nombres designado como predeterminado. Por ejemplo:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

se convierte en:

<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> especifica el nombre del elemento raíz cuando se convierte de JSON, que no tiene un elemento raíz con nombre, a XML.

Por ejemplo, si el JSON tiene el siguiente aspecto:

{
  "abc": "123",
  "efg": "234"
}

Has definido <ObjectRootElementName> como:

<ObjectRootElementName>Root</ObjectRootElementName>

El XML resultante tiene el siguiente aspecto:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

<Options>/<AttributeBlockName>
Elementos <Options>/<AttributePrefix>

<AttributeBlockName> le permite especificar cuándo se convierten los elementos JSON en atributos XML (en lugar de elementos XML).

Por ejemplo, el siguiente ajuste convierte las propiedades de un objeto llamado #attrs en atributos XML:

<AttributeBlockName>#attrs</AttributeBlockName>

El siguiente objeto JSON:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },
        "occupation" : "explorer",
    }
}

se convierte en la siguiente estructura XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix> convierte la propiedad que empieza por el prefijo especificado en atributos XML. Por ejemplo, si el prefijo del atributo es @:

<AttributePrefix>@</AttributePrefix>

Convierte el siguiente objeto JSON:

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

 }
}

a la siguiente estructura XML:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

Elemento <Options>/<ArrayRootElementName>
Elemento <Options>/<ArrayItemElementName>

Convierte una matriz JSON en una lista de elementos XML con los nombres de elemento principal y secundario especificados.

Por ejemplo, los siguientes ajustes:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

convierte la siguiente matriz JSON:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

en la siguiente estructura XML:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

<Options>/<Indent>

Especifica que se debe aplicar sangría a la salida XML. El valor predeterminado es false, lo que significa que no se aplica sangría.

Por ejemplo, el siguiente ajuste configura la política para que indente el resultado:

<Indent>true</Indent>

Si la entrada JSON tiene el siguiente formato:

{"n": [1, 2, 3] }

El resultado sin sangría es el siguiente:

<Array><n>1</n><n>2</n><n>3</n></Array>

Si la sangría está habilitada, el resultado es el siguiente:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

Elemento <Options>/<TextNodeName>

Convierte una propiedad JSON en un nodo de texto XML con el nombre especificado. Por ejemplo, la siguiente configuración:

<TextNodeName>age</TextNodeName>

Convierte este JSON:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

a esta estructura XML:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

Si no se especifica TextNodeName, se genera el XML con el valor predeterminado de un nodo de texto:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

Elemento <Options>/<NullValue>

Indica un valor nulo. De forma predeterminada, el valor es NULL.

Por ejemplo, el siguiente ajuste:

<NullValue>I_AM_NULL</NullValue>
Convierte el siguiente objeto JSON: 
{"person" : "I_AM_NULL"}

al siguiente elemento XML:

<person></person>

Si no se especifica ningún valor (o se especifica un valor distinto de I_AM_NULL) para el valor nulo, la misma carga útil se convierte en lo siguiente:

<person>I_AM_NULL</person>

Elemento <Options>/<InvalidCharsReplacement>

Para ayudar a gestionar el XML no válido que puede causar problemas con un analizador, esta opción sustituye cualquier elemento JSON que genere XML no válido por la cadena. Por ejemplo, el siguiente ajuste:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Convierte este objeto JSON

{
    "First%%%Name": "John"
}

a esta estructura XML:

<First_Name>John<First_Name>

Notas de uso

En un escenario de mediación típico, una política de JSON a XML en el flujo de solicitudes entrantes suele ir emparejada con una política de XML a JSON en el flujo de respuestas salientes. Al combinar las políticas de esta forma, se puede exponer una API JSON para servicios que solo admiten XML de forma nativa.

A menudo, es útil aplicar la política JSON a XML predeterminada (vacía) y añadir de forma iterativa los elementos de configuración que sean necesarios.

En los casos en los que las APIs se usan en diversas aplicaciones cliente que pueden requerir JSON o XML, el formato de la respuesta se puede definir de forma dinámica configurando políticas de JSON a XML y de XML a JSON para que se ejecuten de forma condicional. Consulta Variables y condiciones de flujo para ver una implementación de este caso.

Esquemas

Referencia de errores

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

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

Temas relacionados