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.
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. Borda
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 | Presença |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
falso | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
falso | Obsoleto |
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 |
N/A Se você omitir esse elemento, será usado o valor do atributo |
---|---|
Presença | 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 |
Presença | Opcional |
Tipo | message |
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 |
Presença | Esse elemento é obrigatório quando a variável definida no elemento <Source> é do tipo string. |
Tipo | message |
<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>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 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
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.
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. | build |
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 . |
build |
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 . |
build |
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. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
This error occurs if the message
variable specified in the <Source> element of the JSON to XML policy is either:
|
build |
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
{ "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>
Temas relacionados
- XML para JSON: política XML para JSON
- Transformação XSL: política de transformação XSL (em inglês)