Política JSONtoXML

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.

Nota: o cabeçalho Content-type HTTP da mensagem de origem tem de ser definido como application/json. Caso contrário, a política não é aplicada, o que significa que é ignorada durante o processamento.

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 name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	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 name da política.
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.

Nota: o cabeçalho Content-type HTTP da mensagem de origem tem de ser definido como application/json. Caso contrário, a política não é aplicada, o que significa que é ignorada durante o processamento.

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>

Converte o seguinte objeto JSON:

{"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

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

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.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

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.
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.
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.
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.
steps.jsontoxml.SourceUnavailable	500	Este erro ocorre se a variável message especificada no elemento <Source> da política de JSON para XML for: Fora do âmbito (não disponível no fluxo específico onde a política está a ser executada) ou Não é possível resolver (não está definido)

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

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

{
  "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