Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
![](https://docs.apigee.com/static/api-platform/images/icon_policy_json-to-xml.jpg?authuser=0000&hl=pt)
O que
Essa política converte mensagens do formato JavaScript Object Notation (JSON) para a linguagem de marcação extensível (XML), oferecendo várias opções para controlar como as mensagens são convertidas.
A política é particularmente útil se você quiser transformar mensagens usando XSL. Depois de converter um payload JSON em XML, use a política de transformação XSL com uma folha de estilo personalizada para executar a transformação necessária.
Supondo que o intent seja converter uma solicitação formatada em JSON em uma solicitação formatada em XML, a política seria anexada a um fluxo de solicitação (por exemplo, Solicitação / ProxyEndpoint / PostFlow).
Amostras
Para uma discussão detalhada sobre a conversão entre JSON e XML, consulte http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.
Como converter uma solicitação
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
Essa configuração usa uma mensagem de solicitação no formato JSON como origem e, em seguida, cria uma
mensagem formatada em XML que é preenchida em request
OutputVariable. Borda
usa automaticamente o conteúdo dessa variável como a mensagem para a próxima etapa de processamento.
Referência de elemento
Veja a seguir elementos e atributos que podem ser configurados com 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>
A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:
Atributo | Descrição | Padrão | Presença |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
falso | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
falso | Obsoleto |
Elemento <DisplayName>
Use em conjunto com o atributo name
para rotular a política no
editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
<DisplayName>Policy Display Name</DisplayName>
Padrão |
N/A Se você omitir esse elemento, será usado o valor do atributo |
---|---|
Presença | Opcional |
Tipo | String |
Elemento <Source>
A variável, a solicitação ou a resposta, que contém a mensagem JSON que você quer converter em XML.
Se <Source>
não estiver definido, ele será tratado como mensagem (o que resolve
quando a política é anexada a um fluxo de solicitação ou uma resposta quando a política está anexada
a um fluxo de resposta).
Se a variável de origem não puder ser resolvida ou resolvida para um tipo não mensagem, a política gerará um erro.
<Source>request</Source>
Padrão | solicitação ou resposta, determinado pelo local em que a política é adicionada ao fluxo do proxy da API |
Presença | Opcional |
Tipo | message |
Elemento <OutputVariable>
Armazena a saída da conversão do formato JSON para XML. Geralmente, esse é o mesmo valor da origem, ou seja, normalmente uma solicitação JSON é convertida em uma solicitação XML.
O payload da mensagem JSON é analisado e convertido em XML, e o cabeçalho de tipo de
conteúdo HTTP da mensagem formatada em XML é definido como text/xml;charset=UTF-8
.
Se OutputVariable
não for especificado, o source
será tratado como
OutputVariable
. Por exemplo, se source
for request
,
então OutputVariable
será definido como request
por padrão.
<OutputVariable>request</OutputVariable>
Padrão | solicitação ou resposta, determinado pelo local em que a política é adicionada ao fluxo do proxy da API |
Presença | Esse elemento é obrigatório quando a variável definida no elemento <Source> é do tipo string. |
Tipo | message |
<Options>/<OmitXmlDeclaration>
Especifica a omissão do namespace XML da saída. O valor padrão é false
,
ou seja, incluir o namespace na saída.
Por exemplo, a configuração a seguir configura a política para omitir o namespace:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
Elementos <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>
JSON não tem suporte para namespaces, enquanto documentos XML geralmente exigem isso.
NamespaceBlockName
permite definir uma propriedade JSON que serve como a origem de uma definição
de namespace no XML que é produzida pela política. Isso significa que o JSON de origem precisa
fornecer uma propriedade que possa ser mapeada em um namespace esperado pelo aplicativo que
consome o XML resultante.
Por exemplo, as seguintes configurações:
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator>
indica que uma propriedade chamada #namespaces
existe no JSON de origem que
contém pelo menos um namespace designado como padrão. Exemplo:
{ "population": { "#namespaces": { "$default": "http://www.w3.org/1999/people", "exp": "http://www.w3.org/1999/explorers" }, "person": "John Smith", "exp:person": "Pedro Cabral" } }
é convertido 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 ao converter do JSON, que não tem um elemento raiz nomeado para XML.
Por exemplo, se o JSON aparecer como:
{ "abc": "123", "efg": "234" }
E defina <ObjectRootElementName> como:
<ObjectRootElementName>Root</ObjectRootElementName>
O XML resultante aparece como:
<Root> <abc>123</abc> <efg>234</efg> </Root>
Elementos <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>
<AttributeBlockName>
permite especificar quando os elementos JSON são
convertidos em atributos XML (em vez de elementos XML).
Por exemplo, a configuração a seguir converte propriedades dentro de um objeto chamado
#attrs
em atributos XML:
<AttributeBlockName>#attrs</AttributeBlockName>
O seguinte objeto JSON:
{ "person" : { "#attrs" : { "firstName" : "John", "lastName" : "Smith" }, "occupation" : "explorer", } }
é convertido para a 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. Onde 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>
Elemento <Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName>
Converte uma matriz JSON em uma lista de elementos XML com nomes de elementos pai e filho especificados.
Por exemplo, as seguintes configuraçõ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 que recue a saída XML. O valor padrão é false
,
sem recuo.
Por exemplo, a seguinte configuração configura a política para recuar a saída:
<Indent>true</Indent>
Se a entrada JSON estiver no formato:
{"n": [1, 2, 3] }
Então, a saída sem ficar em branco é:
<Array><n>1</n><n>2</n><n>3</n></Array>
Com o recuo ativado, a saída é:
<Array> <n>1</n> <n>2</n> <n>3</n> </Array>
Elemento <Options>/<TextNodeName>
Converte uma propriedade JSON em um nó de texto XML com o nome especificado. Por exemplo, a seguinte configuração:
<TextNodeName>age</TextNodeName>
converte este JSON:
{ "person": { "firstName": "John", "lastName": "Smith", "age": 25 } }
nesta estrutura XML:
<person> <firstName>John</firstName>25<lastName>Smith</lastName> </person>
Se TextNodeName
não for especificado, o XML será gerado, usando a configuração padrã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 padrão, o valor é NULL
.
Por exemplo, a seguinte configuração:
<NullValue>I_AM_NULL</NullValue>Converte o seguinte objeto JSON:
{"person" : "I_AM_NULL"}
no seguinte elemento XML:
<person></person>
Quando nenhum valor (ou um valor diferente de I_AM_NULL
) for especificado para o valor nulo,
o mesmo payload será convertido em:
<person>I_AM_NULL</person>
Elemento <Options>/<InvalidCharsReplacement>
Para ajudar a lidar com XML inválido que pode causar problemas com um analisador, essa configuração substitui todos os elementos JSON que produzem XML inválido pela string. Por exemplo, a seguinte configuração:
<InvalidCharsReplacement>_</InvalidCharsReplacement>
Converte este objeto JSON
{ "First%%%Name": "John" }
nesta estrutura XML:
<First_Name>John<First_Name>
Observações sobre o uso
Em um cenário típico de mediação, uma política JSON para XML no fluxo de solicitação de entrada geralmente é pareada com uma política XMLtoJSON no fluxo de resposta de saída. Ao combinar políticas dessa maneira, uma API JSON pode ser exposta para serviços que suportam apenas XML.
Muitas vezes, é útil aplicar a política padrão (vazio) do JSON à XML e adicionar de maneira iterativa os elementos de configuração conforme necessário.
Para cenários em que as APIs são consumidas por diversos aplicativos de clientes que podem exigir JSON e XML, o formato da resposta pode ser definido dinamicamente pela configuração do JSON para XML e XML para políticas JSON que serão executadas condicionalmente. Consulte Variáveis e condições do fluxo para uma implementação desse cenário.
Esquemas
Referência de erros
Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Erros de execução
Esses erros podem ocorrer quando a política é executada.
Código de falha | Status HTTP | Causa | Correção |
---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 | O payload de entrada (JSON) está vazio ou a entrada (JSON) transmitida para a política JSON para XML é inválida ou está malformada. | build |
steps.jsontoxml.InCompatibleTypes |
500 | Esse erro ocorrerá se o tipo da variável definido no elemento <Source> e o
elemento <OutputVariable> não forem os mesmos. É obrigatório que o tipo das
variáveis contidas no elemento <Source> e no elemento <OutputVariable> seja
igual. Os tipos válidos são message e string . |
build |
steps.jsontoxml.InvalidSourceType |
500 | Este erro ocorrerá se o tipo da variável usado para definir o elemento <Source>
for inválido. Os tipos válidos de variável são message e string . |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 | Esse erro ocorrerá se a variável especificada no elemento <Source> da política JSON para
XML for do tipo string e o elemento <OutputVariable> não for definido.
O elemento <OutputVariable> é obrigatório quando a variável definida no elemento <Source>
é do tipo string. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
Esse erro ocorrerá se a variável message
especificada no elemento <Source> da política JSON para XML se enquadrar em uma destas situações:
|
build |
Erros de implantação
Nenhum.
Variáveis de falha
Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.
Variáveis | Onde | Exemplo |
---|---|---|
fault.name="fault_name" |
fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 usuário da política que causou 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>
Temas relacionados
- XML para JSON: política XML para JSON
- Transformação XSL: política de transformação XSL (em inglês)