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. Nem todos os usuários têm necessidade de saber sobre os tipos de política e ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

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

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

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:

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>

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>

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>

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

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

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.

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 XMLtoJSON
• Transformação XSL: política XSLTransform