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. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.
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 | Predeterminado | Presencia |
|---|---|---|---|
name |
El nombre interno de la política. El valor del atributo De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
falso | Opcional |
enabled |
Configúralo como Configúralo como |
true | Opcional |
async |
Este atributo dejó de estar disponible. |
falso | Obsoleta |
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>
| Predeterminada |
N/A Si omites este elemento, se usa el valor del atributo |
|---|---|
| Presencia | Opcional |
| Tipo | String |
Elemento <Source>
La variable, la solicitud o la respuesta, que contiene el mensaje JSON que quieres convertir en XML.
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 |
| Presencia | 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 |
| Presencia | 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 en el resultado. De manera opcional, una línea de declaración XML puede aparecer en la parte superior de un documento XML. Un ejemplo típico se ve de la siguiente manera:
<?xml version="1.0" encoding="UTF-8"?>
En algunos casos, es importante evitar incluir una línea de este tipo 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. Debido a que la declaración debe aparecer solo una vez en un documento, y solo en la parte superior del documento, en ese caso, es importante 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 de XML en el resultado. La siguiente configuración configurará la política para omitir la Declaración XML:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
No hay forma de modificar el contenido de la línea de declaración XML ni de afectarlo en 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 está incluida, 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 | Corregir |
|---|---|---|---|
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. | build |
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. |
build |
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. |
build |
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. |
build |
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:
|
build |
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
{
"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