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
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. | build |
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. |
build |
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. |
build |
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. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
This error occurs if the message
variable specified in the <Source> element of the JSON to XML policy is either:
|
build |
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
- De XML a JSON: política de XML a JSON
- Transformación XSL: política de transformación XSL