Política JSONtoXML

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

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.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

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

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, consulte Como converter entre XML e JSON com a Apigee: o que você precisa saber (em inglês).

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. A Apigee 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	Presence
`name`	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
`continueOnError`	Defina como `false` para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como `true` para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
`enabled`	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
`async`	Esse atributo está obsoleto.	false	Descontinuado

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

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo `name` da política.
Presence	Opcional
Tipo	String

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presence 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
Presence	Opcional
Tipo	mensagem

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
Presence	Esse elemento é obrigatório quando a variável definida no elemento `<Source>` é do tipo string.
Tipo	mensagem

<Options>/<OmitXmlDeclaration>

Especifica a omissão da linha de declaração XML na saída. Uma linha de declaração XML pode aparecer opcionalmente na parte de cima de um documento XML. Um exemplo típico é assim:

<?xml version="1.0" encoding="UTF-8"?>

Em alguns casos, é importante evitar a inclusão dessa linha nos resultados da política. Um bom exemplo é quando você planeja incorporar a saída dessa política como um fragmento em um documento XML maior. Como a declaração precisa aparecer apenas uma vez em um documento e apenas na parte de cima dele, seria importante suprimir a linha de declaração XML no fragmento XML.

O valor padrão dessa opção é false, o que significa que a política vai incluir a linha de declaração XML na saída. A seguinte configuração definirá a política para omitir a declaração XML:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

Não é possível moldar ou afetar o conteúdo da linha de declaração XML pela configuração desta política. A política sempre gera texto codificado em UTF-8 e sempre usa o XML versão 1.0, e a linha de declaração, se estiver incluída, refletirá isso.

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

Temas relacionados

XML para JSON: política XMLtoJSON
Transformação XSL: política XSLTransform

Política JSONtoXML

O que

Amostras

Como converter uma solicitação

Referência de elemento

Atributos <JSONToXML>

Elemento <DisplayName>

Elemento <Source>

Elemento <OutputVariable>

<Options>/<OmitXmlDeclaration>

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

<Options>/<ObjectRootElementName>

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

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

<Options>/<Indent>

Elemento <Options>/<TextNodeName>

Elemento <Options>/<NullValue>

Elemento <Options>/<InvalidCharsReplacement>

Observações sobre uso

Esquemas

Referência de erros

Erros de execução

Erros na implantação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

Temas relacionados

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

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

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