Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
![](https://docs.apigee.com/static/api-platform/images/icon_policy_xml-to-json.jpg?authuser=0000&hl=pt)
O que
Essa política converte mensagens do formato extensível da linguagem de marcação (XML) para o JavaScript Object Notation (JSON), oferecendo várias opções para controlar como as mensagens são convertidas.
Supondo que o intent seja converter uma resposta formatada em XML em uma resposta formatada como JSON, a política será anexada a um fluxo de resposta (por exemplo, Resposta / ProxyEndpoint / PostFlow).
Sobre
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 de backend que suportam apenas XML.
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.
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 resposta
<XMLToJSON name="ConvertToJSON"> <Options> </Options> <OutputVariable>response</OutputVariable> <Source>response</Source> </XMLToJSON>
Essa configuração, que é a configuração mínima necessária para converter XML para
JSON, usa uma mensagem de resposta formatada em XML como origem e, em seguida, cria uma mensagem formatada
em JSON que é preenchida na OutputVariable response
. 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.
<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1"> <DisplayName>XML to JSON 1</DisplayName> <Source>response</Source> <OutputVariable>response</OutputVariable> <Options> <RecognizeNumber>true</RecognizeNumber> <RecognizeBoolean>true</RecognizeBoolean> <RecognizeNull>true</RecognizeNull> <NullValue>NULL</NullValue> <NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName> <NamespaceSeparator>***</NamespaceSeparator> <TextAlwaysAsProperty>true</TextAlwaysAsProperty> <TextNodeName>TEXT</TextNodeName> <AttributeBlockName>FOO_BLOCK</AttributeBlockName> <AttributePrefix>BAR_</AttributePrefix> <OutputPrefix>PREFIX_</OutputPrefix> <OutputSuffix>_SUFFIX</OutputSuffix> <StripLevels>2</StripLevels> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options> <!-- Use Options or Format, not both --> <Format>yahoo</Format> </XMLToJSON>
Atributos <XMLtoJSON>
<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
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, solicitação ou resposta, que contém a mensagem XML que você quer converter para JSON.
O cabeçalho HTTP Content-type da mensagem de origem precisa ser definido como
application/xml
. Caso contrário, a política não é aplicada.
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>response</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 do formato XML para JSON. Esse é geralmente o mesmo valor da fonte, ou seja, geralmente a resposta XML é convertida em uma resposta JSON.
O payload da mensagem XML é analisado e convertido em JSON, e o cabeçalho de tipo de conteúdo HTTP
da mensagem formatada em XML é definido como application/json
.
Se OutputVariable
não for especificado, o source
será tratado como
OutputVariable
. Por exemplo, se source
for response
,
então OutputVariable
será definido como response
por padrão.
<OutputVariable>response</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>
As opções oferecem controle sobre a conversão de XML para JSON. Use o grupo
<Options>
, que permite adicionar configurações de conversão específicas, ou o elemento
<Format>
, que permite fazer referência a um modelo de
opções predefinidas. Não é possível usar <Options>
e
<Format>
.
<Options>
será necessário se <Format>
não for usado.
Elemento <Options>/<RecognizeNumber>
Se for true, os campos numéricos no payload do XML mantêm o formato original.
<RecognizeNumber>true</RecognizeNumber>
Considere o seguinte exemplo de XML:
<a> <b>100</b> <c>value</c> </a>
Se true
, converte em:
{ "a": { "b": 100, "c": "value" } }
Se false
, converte em:
{ "a": { "b": "100", "c": "value" } }
Padrão | falso |
Presença | Opcional |
Tipo | Booleanos |
Elemento <Options>/<RecognizeBoolean>
Permite que a conversão mantenha valores booleanos/falsos em vez de transformar os valores em strings.
<RecognizeBoolean>true</RecognizeBoolean>
Para o seguinte exemplo de XML:
<a> <b>true</b> <c>value</c> </a>
Se true
, converte em:
{ "a": { "b": true, "c": "value" } }
Se false
, converte em:
{ "a": { "b": "true", "c": "value" } }
Padrão | falso |
Presença | Opcional |
Tipo | Booleanos |
Elemento <Options>/<RecognizeNull>
Permite converter valores vazios em valores nulos.
<RecognizeNull>true</RecognizeNull>
Para o seguinte XML:
<a> <b></b> <c>value</c> </a>
Se true
, converte em:
{ "a": { "b": null, "c": "value" } }
Se false
, converte em:
{ "a": { "b": {}, "c": "value" } }
Padrão | falso |
Presença | Opcional |
Tipo | Booleanos |
Elemento <Options>/<NullValue>
Indica o valor para o qual valores nulos reconhecidos na mensagem de origem serão
convertidos. Por padrão, o valor é null
. Essa opção só será eficaz
se RecognizeNull
for verdadeiro.
<NullValue>not-present</NullValue>
Padrão | null |
Presença | Opcional |
Tipo | String |
Elementos <Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>
Use esses elementos juntos.
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName> <NamespaceSeparator>***</NamespaceSeparator>
Considere o seguinte exemplo de XML:
<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com"> <ns1:b>value</ns1:b> </a>
Se NamespaceSeparator
não for especificado, a seguinte estrutura JSON será
gerada:
{ "a": { "b": "value" } }
Se os elementos NamespaceBlockName
, DefaultNamespaceNodeName
e
NamespaceSeparator
forem especificados como #namespaces
, &
e ***
, respectivamente, a seguinte estrutura JSON é gerado:
{ "a": { "#namespaces": { "&": "http://ns.com", "ns1": "http://ns1.com" }, "ns1***b": "value" } }
Padrão | Veja exemplos acima. |
Presença | Opcional No entanto, se você especificar <NamespaceBlockName> , deverá também especificar
os outros dois elementos. |
Tipo | Strings |
Elementos <Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>
Use esses elementos juntos.
Se definido como true
, o conteúdo do elemento XML será convertido em uma propriedade de
string.
<TextAlwaysAsProperty>true</TextAlwaysAsProperty> <TextNodeName>TEXT</TextNodeName>
Para o seguinte XML:
<a> <b>value1</b> <c>value2<d>value3</d>value4</c> </a>
Se TextAlwaysAsProperty
for definido como true
e TextNodeName
for especificado como TEXT
, a seguinte estrutura JSON será gerada:
{ "a": { "b": { "TEXT": "value1" }, "c": { "TEXT": [ "value2", "value4" ], "d": { "TEXT": "value3" } } } }
Se TextAlwaysAsProperty
for definido como false
e
TextNodeName
especificado como TEXT
, a seguinte estrutura JSON será
gerada:
{ "a": { "b": "value1", "c": { "TEXT": [ "value2", "value4" ], { "d": "value3", } } }
Padrão | <TextAlwaysAsProperty> : falso<TextNodeName> : N/A |
Presença | Opcional |
Tipo | <TextAlwaysAsProperty> : booleano<TextNodeName> : string |
Elementos <Options>/<AttributeBlockName>
<Options>/<AttributePrefix>
Use esses elementos juntos.
Permite agrupar valores em um bloco JSON e anexar prefixos aos nomes de atributos.
<AttributeBlockName>FOO_BLOCK</AttributeBlockName> <AttributePrefix>BAR_</AttributePrefix>
Considere o seguinte exemplo de XML:
<a attrib1="value1" attrib2="value2"/>
Se ambos os atributos (AttributeBlockName
e AttributePrefix
) forem
especificados conforme definido no exemplo de XML para JSON, a seguinte estrutura JSON será gerada:
{ "a": { "FOO_BLOCK": { "BAR_attrib1": "value1", "BAR_attrib2": "value2" } } }
Se apenas AttributeBlockName
for especificado, a seguinte estrutura JSON será
gerada:
{ "a": { "FOO_BLOCK": { "attrib1": "value1", "attrib2": "value2" } } }
Se apenas AttributePrefix
for especificado, a seguinte estrutura JSON será
gerada:
{ "a": { "BAR_attrib1": "value1", "BAR_attrib2": "value2" } }
Se nenhum deles for especificado, a seguinte estrutura JSON será gerada:
{ "a": { "attrib1": "value1", "attrib2": "value2" } }
Padrão | Veja exemplos acima. |
Presença | Opcional |
Tipo | String |
Elementos <Options>/<OutputPrefix>
<Options>/<OutputSuffix>
Use esses elementos juntos.
<OutputPrefix>PREFIX_</OutputPrefix> <OutputSuffix>_SUFFIX</OutputSuffix>
Considere o seguinte exemplo de XML:
<a>value</a>
Se ambos os atributos (OutputPrefix
e OutputSuffix
) forem especificados
conforme definido no exemplo de XML para JSON, a seguinte estrutura JSON será gerada:
PREFIX_{ "a": "value" }_SUFFIX
Se apenas OutputPrefix
for especificado, a seguinte estrutura JSON será gerada:
PREFIX_{ "a" : "value" }
Se apenas OutputSuffix
for especificado, a seguinte estrutura JSON será gerada:
{ "a" : "value" }_SUFFIX
Se OutputPrefix
e OutputSuffix
não forem especificados, a seguinte
estrutura JSON será gerada:
{ "a": "value" }
Padrão | Veja os exemplos acima. |
Presença | Opcional |
Tipo | String |
Elemento <Options>/<StripLevels>
<Options> <StripLevels>4</StripLevels> </Options>
payloadss vezes, os payloads XML, como o SOAP, têm muitos níveis pais que você não quer incluir no JSON convertido. Veja um exemplo de resposta SOAP com muitos níveis:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/"> <GetCityWeatherByZIPResult> <State>CO</State> <City>Denver</City> <Description>Sunny</Description> <Temperature>62</Temperature> </GetCityWeatherByZIPResult> </GetCityWeatherByZIPResponse> </soap:Body> </soap:Envelope>
Existem quatro níveis antes de chegar ao nível Estado, Cidade, Descrição e Temperatura.
Sem usar <StripLevels>
, a resposta JSON convertida seria
assim:
{ "Envelope" : { "Body" : { "GetCityWeatherByZIPResponse" : { "GetCityWeatherByZIPResult" : { "State" : "CO", "City" : "Denver", "Description" : "Sunny", "Temperature" : "62" } } } } }
Se você quiser retirar esses quatro níveis na resposta JSON,
<StripLevels>4</StripLevels>
, que fornece o seguinte
JSON:
{ "State" : "CO", "City" : "Denver", "Description" : "Sunny", "Temperature" : "62" }
Você pode eliminar os níveis até o primeiro elemento que contém vários filhos. O que isso significa? Vamos analisar um exemplo JSON mais complexo:
{ "Envelope" : { "Body" : { "GetCityForecastByZIPResponse" : { "GetCityForecastByZIPResult" : { "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
O nível 3 neste exemplo é GetCityForecastByZIPResponse
, que tem apenas um
filho. Se você usasse <StripLevels>3</StripLevels>
(remova os
três primeiros níveis), o JSON ficaria assim:
{ "GetCityForecastByZIPResult" : { "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
GetCityForecastByZIPResult
tem vários filhos. Como é o
primeiro elemento que contém vários filhos, é possível remover esse último nível usando
<StripLevels>4</StripLevels>
, que fornecerá o seguinte
JSON:
{ "ResponseText" : "City Found", "ForecastResult" : { "Forecast" : [ { "ProbabilityOfPrecipiation" : { "Nighttime" : "00", "Daytime" : 10 } ...
Como o nível 4 é o primeiro que contém vários filhos, não é possível remover níveis inferiores a esse. Se você definir o nível da faixa como 5, 6, 7 e assim por diante, continuará recebendo a resposta acima.
Padrão | 0 (sem remoção de nível) |
Presença | Opcional |
Tipo | Inteiro |
Elemento <Options>/<TreatAsArray>/<Path>
<Options> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
Essa combinação de elementos permite garantir que os valores de um documento XML sejam colocados em uma matriz
JSON. Isso é útil, por exemplo, quando o número de elementos filhos pode variar (de um a
vários), e você quer garantir que os valores estejam sempre em uma matriz. Isso ajuda a manter seu
código estável, porque você pode conseguir dados da matriz da mesma forma todas as vezes. Por
exemplo: $.teachers.teacher.studentnames[0]
recebe o primeiro valor do nome do aluno
na matriz, independentemente do número de valores na matriz.
Vamos voltar e analisar o comportamento padrão do XML para o JSON e, em seguida, explorar como
controlar a saída usando <TreatAsArray>/<Path>
.
Quando um documento XML contém um elemento com diversos valores filhos (geralmente com base em um esquema
em que o elemento maxOccurs='unbounded'
), a política XML para JSON
coloca esses valores automaticamente em uma matriz. Por exemplo, o seguinte bloco XML
<teacher> <name>teacherA</name> <studentnames> <name>student1</name> <name>student2</name> </studentnames> </teacher>
.…é convertido no seguinte JSON automaticamente, sem configuração de política especial:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]} } } }
Observe que os dois nomes dos alunos são colocados em uma matriz.
No entanto, se apenas um aluno aparecer no documento XML, a política XML para JSON tratará automaticamente o valor como uma única string, não como uma matriz de strings, conforme mostrado no exemplo a seguir:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : "student1" } } } }
Nos exemplos anteriores, os dados semelhantes eram convertidos de maneira diferente, uma vez como uma matriz, outra como
uma única string. É aqui que o elemento <TreatAsArray>/<Path>
permite
controlar a saída. É possível, por exemplo, garantir que os nomes de alunos sejam sempre colocados
em uma matriz, mesmo que haja apenas um valor. Para configurar isso, identifique o caminho para
o elemento com valores que você quer colocar em uma matriz, como:
<Options> <TreatAsArray> <Path>teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
A configuração acima gravaria o JSON assim:
{ "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : ["student1"] } ] } } }
Observe que student1 agora está em uma matriz. Agora, independentemente de haver um ou vários
alunos, é possível recuperá-los de uma matriz JSON no seu código usando o seguinte JSONPath:
$.teachers.teacher.studentnames.name[0]
O elemento <Path>
também tem um atributo unwrap
, explicado
na próxima seção.
Padrão | NA |
Presença | Opcional |
Tipo | String |
Atributos
<Options> <TreatAsArray> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> </Options>
Atributo | Descrição | Presença | Tipo |
---|---|---|---|
unwrap |
Padrão: false Remove o elemento da saída JSON. Use-o para simplificar ou nivelar ("desencapsular")
o JSON, o que também encurta o JSONPath necessário para recuperar valores. Por exemplo,
em vez de Veja um exemplo de JSON: { "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]}... Nesse exemplo, você poderia dizer que o elemento <TreatAsArray> <Path unwrap="true">teachers/teacher</Path> <Path unwrap="true">teachers/teacher/studentnames/name</Path> </TreatAsArray> O atributo { "teachers" : [{ "name" : "teacherA", "studentnames" : ["student1","student2"] }]... Observe que, como o elemento |
Opcional | Booleano |
Para mais exemplos e instruções sobre os recursos, consulte este artigo da comunidade Apigee: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html (link em inglês).
<Format>
O formato permite que você controle a conversão de XML para JSON. Digite o nome de um modelo
predefinido que contém uma combinação específica de elementos Options descritos neste tópico.
Os formatos predefinidos incluem: xml.com
, yahoo
, google
,
badgerFish
.
Use o elemento <Format>
ou o grupo <Options>
. Não é possível usar
<Format>
e <Options>
.
Veja a seguir as definições de formato de cada modelo predefinido.
xml.com
<RecognizeNull>true</RecognizeNull> <TextNodeName>#text</TextNodeName> <AttributePrefix>@</AttributePrefix>
yahoo
<RecognizeNumber>true</RecognizeNumber> <TextNodeName>content</TextNodeName>
<TextNodeName>$t</TextNodeName> <NamespaceSeparator>$</NamespaceSeparator> <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
badgerFish
<TextNodeName>$</TextNodeName> <TextAlwaysAsProperty>true</TextAlwaysAsProperty> <AttributePrefix>@</AttributePrefix> <NamespaceSeparator>:</NamespaceSeparator> <NamespaceBlockName>@xmlns</NamespaceBlockName> <DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>
Sintaxe do elemento:
<Format>yahoo</Format>
Padrão | Insira o nome de um formato disponível:xml.com , yahoo , google , badgerFish |
Presença | Obrigatório se <Options> não for usado. |
Tipo | String |
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.
Código de falha | Status HTTP | Causa | Correção |
---|---|---|---|
steps.xmltojson.ExecutionFailed |
500 | Este erro ocorre quando o payload de entrada (XML) está vazio ou o XML de entrada é inválido ou está malformado. | build |
steps.xmltojson.InCompatibleType |
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> sejam iguais.
|
build |
steps.xmltojson.InvalidSourceType |
500 | Esse erro ocorre se o tipo da variável usada para definir o elemento <Source> é
inválida. Os tipos válidos de variável são mensagem e string. |
build |
steps.xmltojson.OutputVariableIsNotAvailable |
500 | Esse erro ocorre se a variável especificada no elemento <Source> da política XML para
JSON é do tipo string e o elemento <OutputVariable> não é definido.
O elemento <OutputVariable> é obrigatório quando a variável definida no elemento <Source>
é do tipo string. |
build |
steps.xmltojson.SourceUnavailable |
500 |
Esse erro ocorre se a variável message
especificada no elemento <Source> da política XML para JSON for:
|
build |
Erros de implantação
Esses erros podem ocorrer quando você implanta um proxy que contém essa política.
Erro de nome | Causa | Correção |
---|---|---|
EitherOptionOrFormat |
Se um dos elementos <Options> ou <Format> não for
declarado na política XML para JSON, a implantação do proxy da API falhará.
|
build |
UnknownFormat |
Se o elemento <Format> na política XML para JSON tiver um formato desconhecido
definido, a implantação do proxy de API falhará. Os formatos predefinidos incluem:
xml.com , yahoo , google e badgerFish .
|
build |
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 = "SourceUnavailable" |
xmltojson.policy_name.failed |
policy_name é o nome especificado pelo usuário da política que causou a falha. | xmltojson.XMLtoJSON-1.failed = true |
Exemplo de resposta de erro
{ "fault": { "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available", "detail": { "errorcode": "steps.xml2json.SourceUnavailable" } } }
Exemplo de regra de falha
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults"> <Step> <Name>AM-SourceUnavailableMessage</Name> <Condition>(fault.name Matches "SourceUnavailable") </Condition> </Step> <Step> <Name>AM-BadXML</Name> <Condition>(fault.name = "ExecutionFailed")</Condition> </Step> <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition> </FaultRule>
Temas relacionados
JSON para XML: política JSON para XML