Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
O quê
Esta política converte mensagens do formato JavaScript Object Notation (JSON) para linguagem de marcação extensível (XML), o que lhe dá várias opções para controlar a forma como as mensagens são convertidas.
A política é particularmente útil se quiser transformar mensagens através de XSL. Depois de converter um payload JSON em XML, use a política de transformação XSL com uma folha de estilos personalizada para fazer a transformação de que precisa.
Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.
Partindo do princípio de que a intenção é converter um pedido formatado em JSON num pedido formatado em XML, a política seria anexada a um fluxo de pedidos (por exemplo, Request / ProxyEndpoint/ PostFlow).
Amostras
Para uma discussão detalhada, consulte o artigo Converter entre XML e JSON com o Apigee: o que precisa de saber.
Converter um pedido
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
Esta configuração usa uma mensagem de pedido no formato JSON como origem e, em seguida, cria uma mensagem no formato XML que é preenchida na OutputVariable request
. O Apigee usa automaticamente o conteúdo desta variável como a mensagem para o passo de processamento seguinte.
Referência do elemento
Seguem-se os elementos e os atributos que pode configurar nesta 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>
A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:
Atributo | Descrição | Predefinição | Presença |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatória |
continueOnError |
Definido como Definido como |
falso | Opcional |
enabled |
Defina como Defina como |
verdadeiro | Opcional |
async |
Este atributo foi descontinuado. |
falso | Descontinuado |
Elemento <DisplayName>
Use em conjunto com o atributo name
para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
<DisplayName>Policy Display Name</DisplayName>
Predefinição |
N/A Se omitir este elemento, é usado o valor do atributo |
---|---|
Presença | Opcional |
Tipo | String |
Elemento <Source>
A variável, o pedido ou a resposta que contém a mensagem JSON que quer converter em XML.
Se <Source>
não estiver definido, é tratado como mensagem (que é resolvida
para pedido quando a política está anexada a um fluxo de pedidos ou resposta quando a política está anexada
a um fluxo de respostas).
Se a variável de origem não puder ser resolvida ou for resolvida para um tipo que não seja de mensagem, a política gera um erro.
<Source>request</Source>
Predefinição | pedido ou resposta, determinado pelo local onde a política é adicionada ao fluxo do proxy de API |
Presença | Opcional |
Tipo | mensagem |
Elemento <OutputVariable>
Armazena o resultado da conversão do formato JSON para XML. Normalmente, este é o mesmo valor que a origem, ou seja, normalmente, um pedido JSON é convertido num pedido XML.
A carga útil da mensagem JSON é analisada e convertida em XML, e o cabeçalho HTTP Content-type
da mensagem formatada em XML é definido como text/xml;charset=UTF-8
.
Se OutputVariable
não for especificado, source
é tratado como
OutputVariable
. Por exemplo, se o valor de source
for request
,
o valor de OutputVariable
é predefinido como request
.
<OutputVariable>request</OutputVariable>
Predefinição | pedido ou resposta, determinado pelo local onde a política é adicionada ao fluxo do proxy de API |
Presença | Este elemento é obrigatório quando a variável definida no elemento <Source> é do tipo string. |
Tipo | mensagem |
<Options>/<OmitXmlDeclaration>
Especifica que a linha de declaração XML deve ser omitida da saída. Uma linha de declaração XML pode aparecer opcionalmente na parte superior de um documento XML. Um exemplo típico tem o seguinte aspeto:
<?xml version="1.0" encoding="UTF-8"?>
Em alguns casos, é importante evitar incluir essa linha no resultado desta política. Um bom exemplo é se planear incorporar o resultado desta política como um fragmento num documento XML maior. Uma vez que a declaração tem de aparecer apenas uma vez num documento e apenas na parte superior do documento, seria importante nesse caso suprimir a linha de declaração XML no fragmento XML.
O valor predefinido para esta opção é false
, o que significa que
a política vai incluir a linha de declaração XML no resultado. A seguinte
definição configura a política para omitir a declaração XML:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
Não é possível moldar nem afetar o conteúdo da linha de declaração XML através da configuração desta política. A política gera sempre texto codificado em UTF-8 e usa sempre a versão 1.0 do XML. Se a linha de declaração estiver incluída, reflete essa situação.
<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Elementos <Options>/<NamespaceSeparator>
O JSON não suporta espaços de nomes, enquanto os documentos XML os requerem frequentemente.
NamespaceBlockName
permite-lhe definir uma propriedade JSON que serve como origem de uma definição de espaço de nomes no XML produzido pela política. (Isto significa que o JSON de origem tem de fornecer uma propriedade que possa ser mapeada num espaço de nomes esperado pela aplicação que consome o XML resultante.)
Por exemplo, as seguintes definições:
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator>
indica que existe uma propriedade denominada #namespaces
no JSON de origem que
contém, pelo menos, um espaço de nomes designado como predefinição. Por exemplo:
{ "population": { "#namespaces": { "$default": "http://www.w3.org/1999/people", "exp": "http://www.w3.org/1999/explorers" }, "person": "John Smith", "exp:person": "Pedro Cabral" } }
converte-se em:
<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 o nome do elemento raiz quando converte de JSON, que não tem um elemento raiz denominado, para XML.
Por exemplo, se o JSON for apresentado da seguinte forma:
{ "abc": "123", "efg": "234" }
E definiu <ObjectRootElementName> como:
<ObjectRootElementName>Root</ObjectRootElementName>
O XML resultante é apresentado da seguinte forma:
<Root> <abc>123</abc> <efg>234</efg> </Root>
<Options>/<AttributeBlockName>
Elementos <Options>/<AttributePrefix>
<AttributeBlockName>
permite-lhe especificar quando os elementos JSON são convertidos em atributos XML (em vez de elementos XML).
Por exemplo, a seguinte definição converte as propriedades num objeto com o nome
#attrs
em atributos XML:
<AttributeBlockName>#attrs</AttributeBlockName>
O seguinte objeto JSON:
{ "person" : { "#attrs" : { "firstName" : "John", "lastName" : "Smith" }, "occupation" : "explorer", } }
é convertido na seguinte estrutura XML:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<AttributePrefix>
converte a propriedade que começa com o prefixo especificado
em atributos XML. Quando o prefixo do atributo está definido como @
, por exemplo:
<AttributePrefix>@</AttributePrefix>
Converte o seguinte objeto JSON:
{ "person" : { "@firstName" : "John", "@lastName" : "Smith" "occupation" : "explorer", } }
para a seguinte estrutura XML:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<Options>/<ArrayRootElementName>
Elemento <Options>/<ArrayItemElementName>
Converte uma matriz JSON numa lista de elementos XML com nomes de elementos principais e subordinados especificados.
Por exemplo, as seguintes definições:
<ArrayRootElementName>Array</ArrayRootElementName> <ArrayItemElementName>Item</ArrayItemElementName>
converte a seguinte matriz JSON:
[ "John Cabot", { "explorer": "Pedro Cabral" }, "John Smith" ]
na seguinte estrutura XML:
<Array> <Item>John Cabot</Item> <Item> <explorer>Pedro Cabral</explorer> </Item> <Item>John Smith</Item> </Array>
<Options>/<Indent>
Especifica a indentação da saída XML. O valor predefinido é false
o que significa não aplicar indentação.
Por exemplo, a seguinte definição configura a política para aplicar uma indentação à saída:
<Indent>true</Indent>
Se a entrada JSON estiver no formato:
{"n": [1, 2, 3] }
Em seguida, a saída sem recuo é:
<Array><n>1</n><n>2</n><n>3</n></Array>
Com a indentação ativada, o resultado é:
<Array> <n>1</n> <n>2</n> <n>3</n> </Array>
Elemento <Options>/<TextNodeName>
Converte uma propriedade JSON num nó de texto XML com o nome especificado. Por exemplo, a seguinte definição:
<TextNodeName>age</TextNodeName>
converte este JSON:
{ "person": { "firstName": "John", "lastName": "Smith", "age": 25 } }
para esta estrutura XML:
<person> <firstName>John</firstName>25<lastName>Smith</lastName> </person>
Se TextNodeName
não for especificado, o XML é gerado com a predefinição
para um nó de texto:
<person> <firstName>John</firstName> <age>25</age> <lastName>Smith</lastName> </person>
Elemento <Options>/<NullValue>
Indica um valor nulo. Por predefinição, o valor é NULL
.
Por exemplo, a seguinte definição:
<NullValue>I_AM_NULL</NullValue>
{"person" : "I_AM_NULL"}
ao seguinte elemento XML:
<person></person>
Quando não é especificado nenhum valor (ou um valor diferente de I_AM_NULL
) para o valor nulo,
o mesmo payload é convertido em:
<person>I_AM_NULL</person>
Elemento <Options>/<InvalidCharsReplacement>
Para ajudar a processar XML inválido que possa causar problemas com um analisador, esta definição substitui todos os elementos JSON que produzem XML inválido pela string. Por exemplo, a seguinte definição:
<InvalidCharsReplacement>_</InvalidCharsReplacement>
Converte este objeto JSON
{ "First%%%Name": "John" }
para esta estrutura XML:
<First_Name>John<First_Name>
Notas de utilização
Num cenário de mediação típico, uma política de JSON para XML no fluxo de pedidos de entrada é frequentemente associada a uma política de XML para JSON no fluxo de respostas de saída. Ao combinar as políticas desta forma, pode expor uma API JSON para serviços que suportam nativamente apenas XML.
É frequentemente útil aplicar a política JSON para XML predefinida (vazia) e adicionar iterativamente elementos de configuração conforme necessário.
Para cenários em que as APIs são consumidas por diversas apps de cliente que podem exigir JSON e XML, o formato da resposta pode ser definido dinamicamente configurando políticas de JSON para XML e de XML para JSON para execução condicional. Consulte as variáveis e condições do fluxo para uma implementação deste cenário.
Esquemas
Referência de erro
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>
Tópicos relacionados
- XML para JSON: política XMLtoJSON
- Transformação XSL: política XSLTransform