Política JSONtoXML

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

Consulta la documentación de Apigee Edge.

Qué

Esta política convierte los mensajes del formato de notación de objetos JavaScript (JSON) al lenguaje de marcado extensible (XML), lo que te 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.

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.

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

Ejemplos

Para obtener información detallada, consulta el artículo Convertir entre XML y JSON con Apigee: lo que debes saber.

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

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:

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>

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>

Elemento <OutputVariable>

Almacena el resultado de la conversión de formato JSON a XML. Normalmente, es el mismo valor que el origen, 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>

<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 opcionalmente 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 esa 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 debe 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 hay forma de dar forma o 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 hay 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>

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

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

En esta sección se describen los códigos de error y los mensajes de error que se devuelven, así como las variables de error que define Apigee cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionar los errores. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Errores de implementación

Ninguno

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Ejemplo de respuesta de error

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Regla de fallo de ejemplo

<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

• De XML a JSON: política XMLtoJSON
• Transformación XSL: política XSLTransform