Política JSONtoXML

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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.

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

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

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

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

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.

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)