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
Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Como processar falhas.
Erros de tempo de execução
Estes erros podem ocorrer quando a política é executada.
Código de falha | Estado de HTTP | Causa | Corrigir |
---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 |
O payload de entrada (JSON) está vazio ou a entrada (JSON) transmitida para a política de JSON para XML é inválida ou tem um formato incorreto. | build |
steps.jsontoxml.InCompatibleTypes |
500 |
Este erro ocorre se o tipo da variável definida no elemento <Source> e no elemento <OutputVariable> não for o mesmo. É obrigatório que o tipo das variáveis contidas no elemento <Source> e no elemento <OutputVariable> corresponda. Os tipos válidos são message e string . |
build |
steps.jsontoxml.InvalidSourceType |
500 |
Este erro ocorre se o tipo da variável usada para definir o elemento <Source> for inválido. Os tipos válidos de variáveis são message e string . |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 |
Este erro ocorre se a variável especificada no elemento <Source> da política de JSON para XML for do tipo string e o elemento <OutputVariable> não estiver definido.
O elemento <OutputVariable> é obrigatório quando a variável definida no elemento <Source>
é do tipo string. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
Este erro ocorre se a variável message
especificada no elemento <Source> da política de JSON para XML for:
|
build |
Erros de implementação
Nenhum.
Variáveis de falha
Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.
Variáveis | Onde | Exemplo |
---|---|---|
fault.name="fault_name" |
fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha. | fault.name Matches "SourceUnavailable" |
jsontoxml.policy_name.failed |
policy_name é o nome especificado pelo utilizador da política que gerou a falha. | jsontoxml.JSON-to-XML-1.failed = true |
Exemplo de resposta de erro
{ "fault": { "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available", "detail": { "errorcode": "steps.json2xml.SourceUnavailable" } } }
Exemplo de regra de falha
<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