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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.jsontoxml.ExecutionFailed	500	The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes	500	This error occurs if the type of the variable defined in the <Source> element and the <OutputVariable> element are not the same. It is mandatory that the type of the variables contained within the <Source> element and the <OutputVariable> element matches. The valid types are message and string.
steps.jsontoxml.InvalidSourceType	500	This error occurs if the type of the variable used to define the <Source> element is invalid. The valid types of variable are message and string.
steps.jsontoxml.OutputVariableIsNotAvailable	500	This error occurs if the variable specified in the <Source> element of the JSON to XML Policy is of type string and the <OutputVariable> element is not defined. The <OutputVariable> element is mandatory when the variable defined in the <Source> element is of type string.
steps.jsontoxml.SourceUnavailable	500	This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	jsontoxml.JSON-to-XML-1.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

Example fault rule

<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