Política JSONtoXML

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política JSONtoXML converte mensagens do formato JavaScript Object Notation (JSON) para o formato extensible markup language (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.

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).

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.

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 formatada em JSON como origem e, em seguida, cria uma mensagem formatada em 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

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo `name` da política.
Presença	Opcional
Tipo	String

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.

Se <Source> não estiver definido, é tratado como mensagem (que é resolvido 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 inclui a linha de declaração XML na saída. 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 como:

{
  "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 denominado #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 Variáveis e condições de fluxo para uma implementação deste cenário.

Esquemas

Referência de erro

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas e as variáveis com falha definidas pela Apigee quando essa 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
`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.
`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`.
`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`.
`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.
`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: Fora do escopo (não disponível no fluxo específico em que a política está sendo executada) ou Não é possível resolver (não está definida)

Erros na 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

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele 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

Política JSONtoXML Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Amostras

Converter um pedido

Referência do elemento

Atributos <JSONToXML>

Elemento <DisplayName>

Elemento <Source>

Elemento <OutputVariable>

<Options>/<OmitXmlDeclaration>

<Options>/<NamespaceBlockName> <Options>/<DefaultNamespaceNodeName> Elementos <Options>/<NamespaceSeparator>

<Options>/<ObjectRootElementName>

<Options>/<AttributeBlockName> Elementos <Options>/<AttributePrefix>

<Options>/<ArrayRootElementName> Elemento <Options>/<ArrayItemElementName>

<Options>/<Indent>

Elemento <Options>/<TextNodeName>

Elemento <Options>/<NullValue>

Elemento <Options>/<InvalidCharsReplacement>

Notas de utilização

Esquemas

Referência de erro

Erros de execução

Erros na implantação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

Tópicos relacionados

Política JSONtoXML

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Elementos <Options>/<NamespaceSeparator>

<Options>/<AttributeBlockName>
Elementos <Options>/<AttributePrefix>

<Options>/<ArrayRootElementName>
Elemento <Options>/<ArrayItemElementName>