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 de JavaScript (JSON) al de lenguaje de marcación extensible (XML), lo que te brinda varias opciones para controlar cómo se convierten los mensajes.

La política es útil en especial si deseas transformar mensajes mediante XSL. Después de convertir una carga útil de JSON a XML, usa la política de transformación XSL con una hoja de estilo personalizada para realizar la transformación que necesitas.

Esta 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 con cada tipo de entorno, consulta Tipos de políticas.

Nota: El encabezado de tipo de contenido HTTP del mensaje de origen se debe configurar como application/json. De lo contrario, no se aplica la política, lo que significa que se omite durante el procesamiento.

Si suponemos que la intención es convertir una solicitud con formato JSON en una solicitud con formato XML, la política se debería adjuntar a un flujo de solicitud (por ejemplo, Request / ProxyEndpoint / PostFlow).

Muestras

Para obtener un análisis detallado, consulta Conversión entre XML y JSON con Apigee: Lo que necesitas saber.

Convierte una solicitud

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

Esta configuración toma un mensaje de solicitud con formato JSON como origen y, luego, crea un mensaje con formato XML que se propaga en la OutputVariable de request. Apigee usa de forma automática el contenido de esta variable como el mensaje para el próximo paso de procesamiento.

Referencia del elemento

A continuación, se describen los elementos y los atributos que puedes 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 <JSONToXML>

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Configuración predeterminada	Presence
`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. De forma opcional, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
`continueOnError`	Configúralo como `false` para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como `true` para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	false	Opcional
`enabled`	Configúralo como `true` para aplicar la política. Configúralo como `false` para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
`async`	Este atributo dejó de estar disponible.	false	Obsoleto

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Configuración predeterminada

Configuración predeterminada	N/A Si omites este elemento, se usa el valor del atributo `name` de la política.
Presence	Opcional
Tipo	String

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presence Opcional

Tipo String

Elemento <Source>

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

Nota: El encabezado de tipo de contenido HTTP del mensaje de origen se debe configurar como application/json. De lo contrario, no se aplica la política, por lo que se omite durante el procesamiento.

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

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

<Source>request</Source>

Predeterminada	solicitud o respuesta, determinadas por la ubicación en la que se agrega la política al flujo del proxy de API
Presence	Opcional
Tipo	mensaje

Elemento <OutputVariable>

Almacena el resultado de la conversión de formato JSON a XML. Por lo general, es el mismo valor que el origen, es decir, una solicitud JSON se suele convertir en una solicitud XML.

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

Si no se especifica OutputVariable, source se trata como OutputVariable. Por ejemplo, si el source es request, entonces OutputVariable se configura de forma predeterminada como request.

<OutputVariable>request</OutputVariable>

Predeterminada	solicitud o respuesta, determinadas por la ubicación en la que se agrega la política al flujo del proxy de API
Presence	Este elemento es obligatorio cuando la variable definida en el elemento `<Source>` es de tipo de string.
Tipo	mensaje

<Options>/<OmitXmlDeclaration>

Especifica que se debe omitir la línea de declaración XML del resultado. De manera opcional, puede aparecer una línea de declaración XML en la parte superior de un documento XML. Un ejemplo típico se ve así:

<?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 planeas incorporar el resultado de esta política como un fragmento en un documento XML más grande. Como la declaración debe aparecer solo una vez en un documento y solo en la parte superior del documento, sería importante en ese caso suprimir la línea de declaración XML en el fragmento XML.

El valor predeterminado para esta opción es false, lo que significa que la política incluirá la línea de declaración XML en el resultado. Con la siguiente configuración, se establecerá que la política omita la declaración XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

No hay forma de dar forma al contenido de la línea de declaración XML ni afectarlo a través de 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, y la línea de declaración, si se incluye, lo reflejará.

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

JSON no admite los espacios de nombres, mientras que los documentos XML a menudo los requieren. NamespaceBlockName te permite definir una propiedad JSON que sirve como origen de la definición de un espacio de nombres en el XML que produce la política. Esto significa que el JSON de origen debe proporcionar una propiedad que se pueda asignar a un espacio de nombres que requiere la aplicación que consume el XML resultante.

Por ejemplo, mediante la siguiente configuración:

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

Se indica que existe una propiedad llamada #namespaces en el archivo 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 lo siguiente:

<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 conviertes de JSON, que no tiene un elemento raíz con nombre, a XML.

Por ejemplo, si el archivo JSON aparece de la siguiente manera:

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

Y configuras <ObjectRootElementName> de la siguiente manera:

<ObjectRootElementName>Root</ObjectRootElementName>

El XML resultante aparecerá de la siguiente manera:

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

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

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

Por ejemplo, la siguiente configuración convierte las propiedades dentro de un objeto llamado #attrs en atributos XML:

<AttributeBlockName>#attrs</AttributeBlockName>

Ten en cuenta 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 comienza con el prefijo especificado en atributos XML. Cuando el prefijo del atributo se configura como @, por ejemplo, sucede lo siguiente:

<AttributePrefix>@</AttributePrefix>

Se convierte el siguiente objeto JSON:

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

 }
}

En la siguiente estructura XML:

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

Elementos <Options>/<ArrayRootElementName>
y <Options>/<ArrayItemElementName>

Convierte un arreglo JSON en una lista de elementos XML con nombres de elementos superiores y secundarios especificados.

Por ejemplo, mediante la siguiente configuración:

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

Se convierte el siguiente arreglo 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 una sangría al resultado de XML. El valor predeterminado es false, lo que significa que no hay sangría.

Por ejemplo, mediante la siguiente configuración, se establece que la política debe aplicar una sangría al resultado:

<Indent>true</Indent>

Si la entrada JSON tiene el siguiente formato:

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

El resultado sin la sangría es el siguiente:

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

Con la sangría 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, mediante la siguiente configuración:

<TextNodeName>age</TextNodeName>

Se convierte este JSON:

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

En esta estructura XML:

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

Si no se especifica TextNodeName, se genera el XML mediante el uso de la configuración predeterminada para un nodo de texto:

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

Elemento <Options>/<NullValue>

Indica un valor nulo. El valor predeterminado es NULL.

Por ejemplo, mediante la siguiente configuración:

<NullValue>I_AM_NULL</NullValue>

Se convierte el siguiente objeto JSON:

{"person" : "I_AM_NULL"}

En el siguiente elemento XML:

<person></person>

Cuando no se especifica ningún valor (o 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 controlar un XML no válido que puede causar problemas con un analizador, esta configuración reemplaza cualquier elemento JSON que produzca un XML no válido por la string. Por ejemplo, mediante la siguiente configuración:

<InvalidCharsReplacement>_</InvalidCharsReplacement>

Se convierte este objeto JSON:

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

En esta estructura XML:

<First_Name>John<First_Name>

Notas de uso

En una situación de mediación típica, una política de JSON a XML en el flujo de solicitud entrante se suele vincular con una política XMLtoJSON en el flujo de respuesta saliente. Cuando se combinan políticas de esta manera, se puede exponer una API de JSON para servicios que solo admiten XML de forma nativa.

A menudo, resulta útil aplicar la política predeterminada (vacía) de JSON a XML y agregar de forma iterativa los elementos de configuración según sea necesario.

En las situaciones en las que varias aplicaciones cliente consumen las API pueden requerir JSON y XML, el formato de la respuesta se puede configurar de forma dinámica mediante la configuración de las políticas de JSON a XML y de XML a JSON para ejecutarse de forma condicional. Consulta Variables y condiciones de flujo para ver una implementación de esta situación.

Esquemas

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

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

Código de falla	Estado de HTTP	Causa
`steps.jsontoxml.ExecutionFailed`	`500`	La carga útil de entrada (JSON) está vacía o la entrada (JSON) que se pasó a la política JSON to XML no es válida o presenta errores de formato.
`steps.jsontoxml.InCompatibleTypes`	`500`	Este error se genera si el tipo de variable definida en el elemento `<Source>` y el elemento `<OutputVariable>` no son iguales. Es obligatorio que el tipo de variables incluidas dentro del elemento `<Source>` y el elemento `<OutputVariable>` coincidan. Los tipos válidos son `message` y `string`.
`steps.jsontoxml.InvalidSourceType`	`500`	Este error se genera si el tipo de variable que se usa para definir el elemento `<Source>` no es válido. Los tipos de variable válidos son `message` y `string`.
`steps.jsontoxml.OutputVariableIsNotAvailable`	`500`	Este error se produce si la variable especificada en el elemento `<Source>` de la política JSON a XML es de string de tipo y el elemento `<OutputVariable>` no está definido. El elemento `<OutputVariable>` es obligatorio cuando la variable definida en el elemento `<Source>` es de tipo de string.
`steps.jsontoxml.SourceUnavailable`	`500`	Este error ocurre si la variable message especificada en el elemento `<Source>` de la política JSON a XML tiene una de las siguientes características: Fuera del alcance (no disponible en el flujo específico en el que se ejecuta la política) No se puede resolver (no está definida)

Errores en la implementación

Ninguno

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
`fault.name="fault_name"`	`fault_name` es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	`fault.name Matches "SourceUnavailable"`
`jsontoxml.policy_name.failed`	`policy_name` es el nombre especificado por el usuario de la política que generó la falla.	`jsontoxml.JSON-to-XML-1.failed = true`

Ejemplo de respuesta de error

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Ejemplo de regla de falla

<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 de XML a JSON
Transformación XSL: política de transformación XSL

Política JSONtoXML

Qué

Muestras

Convierte una solicitud

Referencia del elemento

Atributos <JSONToXML>

Elemento <DisplayName>

Elemento <Source>

Elemento <OutputVariable>

<Options>/<OmitXmlDeclaration>

<Options>/<NamespaceBlockName> <Options>/<DefaultNamespaceNodeName> <Options>/<NamespaceSeparator> elements

<Options>/<ObjectRootElementName>

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

Elementos <Options>/<ArrayRootElementName> y <Options>/<ArrayItemElementName>

<Options>/<Indent>

Elemento <Options>/<TextNodeName>

Elemento <Options>/<NullValue>

Elemento <Options>/<InvalidCharsReplacement>

Notas de uso

Esquemas

Referencia de errores

Errores de entorno de ejecución

Errores en la implementación

Variables con fallas

Ejemplo de respuesta de error

Ejemplo de regla de falla

Temas relacionados

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

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

Elementos <Options>/<ArrayRootElementName>
y <Options>/<ArrayItemElementName>