O que é XML

Se você estiver testando APIs, existem dois formatos principais de transferência de dados que você deve conhecer:

• XML - usado em solicitações SOAP (sempre) e REST (com menos frequência) ;
• JSON - usado em solicitações REST.

Hoje vou apresentar o XML.



XML , traduzido do Inglês e X tensible M arkup L anguage é uma linguagem de marcação extensível. Usado para armazenar e transmitir dados. Portanto, você pode ver isso não apenas na API, mas também no código.



Este formato é recomendado pelo World Wide Web Consortium (W3C), por isso é freqüentemente usado para transferir dados por API. Na API SOAP, geralmente esse é o único formato possível para dados de entrada e saída!

Veja também:

O que é uma API - uma introdução geral à API

Introdução ao SOAP e REST: o que é e com que comer - um vídeo sobre a diferença entre SOAP e REST.

Então, vamos descobrir como é, como lê-lo e como quebrá-lo! Sim, sim, mas onde sem ele? Afinal, precisamos descobrir como o sistema reagirá ao formato da curva dos dados enviados.

Conteúdo

• Como funciona o XML
  
  
  • Tag
  • Elemento raiz
  • Valor do item
  • Atributos do elemento
  • Prólogo XML
  • Esquema XSD
  • Prática: redigindo sua solicitação
• XML bem formado
  
  
  • 1. Existe um elemento raiz
  • 2. Cada elemento possui uma tag de fechamento
  • 3. As tags diferenciam maiúsculas de minúsculas
  • 4. Aninhamento correto de elementos
  • 5. Os atributos são colocados entre aspas
• Total

Como funciona o XML

Vamos dar um exemplo da documentação de dicas de nome completo de Dadata :

<req>
<query> </query>
<count>7</count>
</req>

E vamos descobrir o que essa entrada significa.

Tag

Em XML, cada elemento deve ser envolvido em tags. Uma tag é um texto envolvido em colchetes angulares:

<tag>

O texto dentro dos colchetes angulares é o nome da tag.

Sempre há duas tags:

• Abridor - texto entre colchetes angulares

  <tag>

• Fechando - o mesmo texto (isso é importante!), Mas o símbolo "/" é adicionado

  </tag>

Oh, ok, fui pego! Nem sempre. Também existem elementos vazios, eles têm uma tag, abrindo e fechando ao mesmo tempo. Mas mais sobre isso depois!



Com a ajuda de tags mostramos ao sistema “aqui começa o elemento e é aqui que termina”. São como placas de trânsito:



- Na entrada da cidade, seu nome está escrito: Moscou

- Na saída, o mesmo nome está escrito, mas riscado: Moscou *



* Um exemplo de placas de trânsito que li certa vez em um artigo do Yandex, mas não me lembro do link. E um excelente exemplo!

Elemento raiz

Qualquer documento XML possui um elemento raiz. Esta é a marca com a qual o documento começa e termina. No caso da API REST, um documento é uma solicitação que o sistema envia. Ou a resposta que ela obtém.



Para designar essa solicitação, precisamos de um elemento raiz. Nas dicas de ferramentas, o elemento raiz é "req".







Ele poderia ter um nome diferente:

<main>

<sugg>

Sim, tanto faz. Mostra o início e o fim do nosso pedido, nada mais. Mas dentro já está o corpo do documento - a própria solicitação. Esses parâmetros que passamos para o sistema externo. Claro, eles também estarão em tags, mas em tags regulares, não em root.

Valor do item

O valor do elemento é armazenado entre as tags de início e fim. Pode ser um número, uma string ou até mesmo tags aninhadas!



Aqui temos a tag "query". Ele denota a solicitação que enviamos para as dicas.







Inside - o valor da solicitação.







É como se tivéssemos direcionado a linha "Victor Ivan" para a GUI (interface gráfica do usuário): O







usuário não precisa de uma cinta extra, ele precisa de uma forma bonita. Mas o sistema deve de alguma forma transmitir que "o usuário digitou exatamente isso". Como posso mostrar a ela onde o valor passado começa e termina? É para isso que servem as tags.



O sistema vê a tag "consulta" e entende que dentro dela há "uma string para a qual os prompts devem ser retornados". Contagem de







parâmetros = 7indica quantas dicas retornar na resposta. Se você der dicas no formulário de demonstração de Dadata , 7 dicas retornarão para nós. Isso ocorre porque o valor count = 7 está costurado nele . Mas se você consultar a documentação do método , a contagem pode ser selecionada de 1 a 20.

Abra o console do desenvolvedor via f12 , guia Rede , e veja qual solicitação está sendo enviada ao servidor. Haverá uma contagem = 7 .







Veja também:

O que um testador precisa saber sobre o painel do desenvolvedor - Saiba mais sobre como usar o console.

Nota:

• Victor Ivan - string
• 7 - número

Mas ambos os valores vêm sem aspas. Em XML, não precisamos colocar o valor da string entre aspas (mas em JSON, temos que fazer isso).

Atributos do elemento

Um elemento pode ter um ou mais atributos. Nós os indicamos dentro da tag destacável após o nome da tag separado por um espaço no formulário

_ = « »

Por exemplo:

<query attr1=“value 1”> </query>
<query attr1=“value 1” attr2=“value 2”> </query>

Por que isso é necessário? A partir dos atributos, o sistema que recebe a solicitação da API entende o que recebeu.



Por exemplo, fazemos uma pesquisa no sistema, procurando clientes com o nome Oleg. Enviamos um pedido simples:

<query></query>

E em troca recebemos um pacote inteiro de Olegs! Com diferentes datas de nascimento, números de telefone e outros dados. Digamos que um dos resultados da pesquisa seja assim:

<party type="PHYSICAL" sourceSystem="AL" rawId="2">
    <field name=“name"> </field>
    <field name="birthdate">02.01.1980</field>
    <attribute type="PHONE" rawId="AL.2.PH.1">
        <field name="type">MOBILE</field>
        <field name="number">+7 916 1234567</field>
    </attribute>
</party>

Vamos dar uma olhada nesta entrada. Temos a festa do elemento principal .







Possui 3 atributos:

• type = «PHYSICAL» — . , : , , . , . ! , , — ,
• sourceSystem = «AL» — . , , .
• rawId = «2» — . , , . , ? sourceSystem + rawId!

Existem elementos de campo dentro do grupo . Os elementos de campo têm um atributo de nome . O valor do atributo é o nome do campo: nome, data de nascimento, tipo ou número de telefone. É assim que entendemos o que está oculto em um campo específico . Isso é conveniente do ponto de vista do suporte quando você tem um produto embalado e mais de 10 clientes. Cada cliente terá seu próprio conjunto de campos: alguém tem um INN no sistema, outro não, um é importante sobre a data de nascimento, outro não, etc. Mas, apesar da diferença nos modelos, todos os clientes terão um esquema XSD (que descreve a solicitação e a resposta): - há um elemento de festa; - possui elementos de campo;



























- cada elemento de campo possui um atributo de nome que armazena o nome do campo.



Mas os nomes específicos dos campos não podem mais ser descritos no XSD. Eles já estão "olhe no TK". Claro, quando há apenas um cliente ou você está fazendo software para você ou “em geral para todos”, é mais conveniente usar campos nomeados - ou seja, tags de “fala”. Quais são as vantagens desta abordagem:



- Ao ler XSD, os campos reais são imediatamente visíveis. O TK pode estar desatualizado e o código estará atualizado.

- A solicitação é fácil de puxar manualmente no SOAP Ui - ele irá criar imediatamente todos os campos necessários, você só precisa preencher os valores. Isso é conveniente para o testador + o cliente às vezes testa assim, ele também é bom.



Em geral, qualquer abordagem tem o direito de existir. É necessário olhar para o projeto, que será mais conveniente para você. No meu exemplo, tenho nomes de elementos não falados - todos como um só serãocampo . Mas pelos atributos você já pode entender o que é.



Além dos elementos de campo , a parte possui um elemento de atributo . Não confunda notação xml e leitura comercial:

• do ponto de vista empresarial, este é um atributo de um indivíduo, daí o nome do elemento - atributo .
• do ponto de vista do xml é um elemento (não um atributo!), foi simplesmente denominado atributo . XML não se importa (quase) como você nomeia os elementos, então está tudo bem.

O atributo elemento tem atributos:

• type = "PHONE" - tipo de atributo. Afinal, podem ser diferentes: telefone, endereço, email ...
• rawId = "AL.2.PH.1" - identificador no sistema de origem. É necessário para atualização. Afinal, um cliente pode ter vários telefones, como saber qual deles está sendo atualizado sem ID?

Esse é o XML produzido. E simplificado. Em sistemas reais onde os indivíduos são armazenados, há muito mais dados: cerca de 20 campos do próprio indivíduo, vários endereços, números de telefone, endereços de e-mail ...



Mas ler até mesmo um XML enorme não será difícil se você souber onde está. E se for formatado, os elementos aninhados são deslocados para a direita, o resto fica no mesmo nível. Vai ser difícil sem formatar ...



E tudo é tão simples - temos elementos entre tags. Dentro das tags está o nome do elemento. Se houver algo após o nome, separado por um espaço: esses são os atributos do elemento.

Prólogo XML

Às vezes, na parte superior do documento XML, você verá algo semelhante:

<?xml version="1.0" encoding="UTF-8"?>

Essa linha é chamada de prólogo XML. Mostra a versão do XML usada no documento, bem como a codificação. O prólogo é opcional, se não estiver lá - tudo bem. Mas se for, deve ser a primeira linha do documento XML.



UTF-8 é a codificação padrão para documentos XML.

Esquema XSD

XSD ( X ML S chema D efinition) é a sua descrição XML. Como deveria ser, qual deveria ser? Este é o TK escrito na linguagem da máquina - afinal, nós escrevemos o esquema ... Também no formato XML! O resultado é XML que descreve outro XML.



O truque é que a verificação de acordo com o esquema pode ser delegada à máquina. E o desenvolvedor nem precisa agendar todas as verificações. Basta dizer "aqui está um diagrama, verifique".



Se criarmos um método SOAP, indicamos no esquema:

• quais campos estarão na solicitação;
• quais campos estarão na resposta;
• quais tipos de dados cada campo possui;
• quais campos são obrigatórios e quais não são;
• O campo tem um valor padrão e qual é?
• O campo tem um limite de comprimento?
• O campo possui outros parâmetros?
• ;
• ...

Agora, quando um pedido chega até nós, primeiro é verificado se está correto de acordo com o esquema. Se a solicitação estiver correta, lançamos o método e elaboramos a lógica de negócios. E pode ser complexo e usar muitos recursos! Por exemplo, faça uma amostra de um banco de dados multimilionário. Ou conduza uma dúzia de verificações em diferentes tabelas de banco de dados ...



Então, por que executar um procedimento complexo se a consulta é obviamente “ruim”? E dá um erro após 5 minutos, e não imediatamente? A validação do esquema ajuda a filtrar rapidamente as solicitações obviamente inválidas sem sobrecarregar o sistema.







Além disso, alguns programas clientes oferecem proteção semelhante para o envio de solicitações. Por exemplo, SOAP Ui pode verificar sua solicitação de xml bem formado, e ele simplesmente não irá enviá-lo para o servidor se você errar. Economiza tempo na transferência de dados, muito bem!







E para o usuário simples de sua API SOAP, o esquema ajuda a entender como redigir uma solicitação. O que é um “usuário simples”?

1. O desenvolvedor do sistema que usa sua API - ele precisa escrever no código o que exatamente enviar do sistema dele para o seu.
2. Um testador que precisa verificar essa mesma API - ele precisa entender como a solicitação é formada.

Sim, sim, idealmente temos um TK detalhado, onde tudo está bem descrito. Mas, infelizmente, nem sempre é esse o caso. Às vezes, o TK simplesmente não existe e às vezes está desatualizado. Mas o esquema não se tornará obsoleto, porque ele é atualizado quando o código é atualizado. E apenas ajuda a entender como a solicitação deve ser.







Em resumo, como o esquema é usado ao desenvolver a API SOAP:

• Nosso desenvolvedor escreve um esquema XSD para a solicitação da API: você precisa passar um elemento tal e tal, que terá tal e tal filho, com tal e tal tipo de dados. Esses são obrigatórios, aqueles não.
• O desenvolvedor do sistema do cliente, que está integrado ao nosso, lê este diagrama e constrói suas solicitações de acordo com ele.
• O sistema do cliente envia solicitações para nós.
• Nosso sistema verifica as solicitações de XSD - se algo estiver errado, é apenas uma sacudida.
• Se a solicitação XSD passou na verificação, ative a lógica de negócios!

Agora vamos ver como o circuito ficaria! Veja o método doRegister em Usuários, por exemplo . Para enviar um pedido, devemos passar email, nome e senha. Existem várias maneiras de escrever uma consulta certa e errada:





Vamos tentar escrever um diagrama para isso. A solicitação deve conter 3 elementos ( e-mail, nome, senha ) do tipo "string" (string). Nós escrevemos:

<xs:element name="doRegister ">
   <xs:complexType>
   <xs:sequence>
     <xs:element name="email" type="xs:string"/>
     <xs:element name="name" type="xs:string"/>
     <xs:element name="password" type="xs:string"/>
   </xs:sequence>
   </xs:complexType>
</xs:element>

E no WSDl do serviço, está escrito ainda mais fácil:

<message name="doRegisterRequest">
   <part name="email" type="xsd:string"/>
   <part name="name" type="xsd:string"/>
   <part name="password" type="xsd:string"/>
</message>

Claro, pode haver mais do que apenas elementos embutidos em um esquema. Podem ser números, datas, valores booleanos e até mesmo alguns de seus próprios tipos:

<xsd:complexType name="Test">
   <xsd:sequence>
     <xsd:element name="value"   type="xsd:string"/>
     <xsd:element name="include" type="xsd:boolean" minOccurs="0" default="true"/>
     <xsd:element name="count" type="xsd:int" minOccurs="0" length="20"/>
     <xsd:element name="user" type="USER" minOccurs="0"/>
   </xsd:sequence>
</xsd:complexType>

Você também pode se referir a outro esquema em um esquema, o que torna mais fácil escrever código - você pode reutilizar esquemas para diferentes tarefas.



Veja também:

XSD - XML ​​inteligente - artigo útil de habr

Linguagem de definição de esquema XSD - existem tabelas convenientes com valores que você pode usar

XSD Schema Description Language (XML-Schema)

Um exemplo de um esquema XML no tutorial

Site oficial w3.org

Prática: redigindo sua solicitação

Ok, agora sabemos como "ler" uma solicitação de um método API em formato XML. Mas como desenhá-lo de acordo com o TK? Vamos tentar. Nós olhamos a documentação. E é por isso que estou dando um exemplo de Dadata - é uma ótima documentação !







E se eu quiser retornar apenas nomes completos de mulheres que começam com "An"? Vamos pegar nosso exemplo original:

<req>
  <query> </query>
  <count>7</count>
</req>

Em primeiro lugar, alteramos o próprio pedido. Agora não é mais "Victor Ivan", mas "An":

<req>
  <query></query>
  <count>7</count>
</req>

A seguir, olhamos para o TK. Como devolver dicas femininas? Existe um parâmetro especial - gênero . O nome do parâmetro é o nome das tags. E já colocamos o chão dentro. "Feminino" em inglês será FEMININO , na documentação também. Total recebido:

<req>
  <query></query>
  <count>7</count>
  <gender>FEMALE</gender>
</req>

Você pode excluir o desnecessário. Se não nos importamos com o número de dicas, descartamos o parâmetro de contagem. Afinal, de acordo com a documentação, é opcional. Recebeu um pedido:

<req>
  <query></query>
  <gender>FEMALE</gender>
</req>

Isso é tudo! Pegamos um exemplo como base, mudamos um valor, adicionamos um parâmetro, removemos um. Não é tão difícil. Especialmente quando há uma especificação detalhada e um exemplo)))

Tente você mesmo!

Escreva uma solicitação para o método MagicSearch em Usuários. Queremos encontrar todos os Ivanovs por coincidência completa, em que pendem tarefas urgentes.

XML bem formado

Cabe ao desenvolvedor decidir qual XML está correto e qual não é. Mas existem regras gerais que não podem ser violadas. O XML deve estar bem formado, ou seja, sintaticamente correto.



Para verificar a sintaxe de XML, você pode usar qualquer Validador XML (e google). Eu recomendo o site w3schools . Existe o próprio validador + uma descrição de erros típicos com exemplos.



No validador concluído, basta inserir seu XML (por exemplo, uma solicitação para o servidor) e ver se está tudo bem com ele. Mas você mesmo pode verificar. Percorra as regras de sintaxe e veja se sua consulta as segue.



Regras XML bem formadas:

1. Existe um elemento raiz.
2. Cada elemento possui uma tag de fechamento.
3. As tags diferenciam maiúsculas de minúsculas!
4. O aninhamento correto dos elementos é respeitado.
5. Os atributos são colocados entre aspas.

Vamos examinar cada regra e discutir como podemos aplicá-las nos testes. Isto é, como "quebrar" corretamente uma consulta comparando-a com um xml bem formado. Por que isso é necessário? Veja o feedback do sistema. Você pode entender pelo texto do erro exatamente onde você errou?



Veja também:

Mensagens de erro também são documentação, teste-as! - por que testar mensagens de erro

1. Existe um elemento raiz

Você não pode simplesmente colocar 2 XML lado a lado e assumir que "o sistema descobrirá por si mesmo que essas são duas solicitações, não uma." Não vou entender. Porque você não deveria.



E se você tiver várias tags em uma linha sem um pai comum, isso é xml ruim, mal formado. Sempre deve haver um elemento raiz:



O que estamos fazendo para testar essa condição? Isso mesmo, removemos as tags raiz de nosso pedido!

2. Cada elemento possui uma tag de fechamento

Tudo é simples aqui - se uma tag foi aberta em algum lugar, ela deve fechar em algum lugar. Quer fazer uma pausa? Remova a tag de fechamento de qualquer elemento.



Mas aqui é importante notar que pode haver uma tag. Se o elemento estiver vazio, podemos continuar com uma tag, fechando-o no final:

<name/>

Isso é o mesmo que passar um valor vazio nele

<name></name>

Da mesma forma, o servidor pode nos retornar um valor de tag vazio. Você pode tentar enviar campos vazios para usuários no método FullUpdateUser . E isso é aceitável na solicitação (enviei o campo name1 vazio ), e na resposta SOAP Ui, ele renderiza exatamente os campos vazios.







Total - se houver uma tag de abertura, deve haver uma tag de fechamento. Ou será uma tag com uma barra no final.



Para teste, remova qualquer tag de fechamento na solicitação.

3. As tags diferenciam maiúsculas de minúsculas

Como eles escreveram o de abertura - nós também escrevemos o de fechamento. SEMELHANTE! E não do jeito que você queria.



Mas para teste, mudamos o registro de uma das partes. Esse XML será inválido

4. Aninhamento correto de elementos

Os elementos podem ir um após o outro







Um elemento pode ser aninhado em outro,







mas os elementos NÃO podem se sobrepor!

5. Os atributos são colocados entre aspas

Mesmo se você considerar o atributo um número, ele será entre aspas:

<query attr1=“123”> </query>
<query attr1=“” attr2=“123” > </query>

Para fins de teste, tentamos passar sem as aspas:

<query attr1=123> </query>

Total

XML (e X tensible M arkup L anguage) é usado para armazenar e transferir dados.

— API-. SOAP-, . SOAP XML. REST, — XML, JSON.



— XML . , . XML - , , - .



XML open-source folks. , JacksonJsonProvider, «» — , (featuresToEnable), , (featuresToDisable).

O formato XML segue padrões. Um pedido sintaticamente incorreto nem vai para o servidor, o cliente vai cortá-lo. Bem formado primeiro, depois a lógica de negócios.



Regras XML bem formadas:

1. Existe um elemento raiz.
2. Cada elemento possui uma tag de fechamento.
3. As tags diferenciam maiúsculas de minúsculas!
4. O aninhamento correto dos elementos é respeitado.
5. Os atributos são colocados entre aspas.

Se você for um testador, ao testar consultas XML, certifique-se de tentar quebrar todas as regras! Sim, o sistema deve ser capaz de lidar com esses erros e retornar uma mensagem de erro adequada. Mas ela nem sempre faz isso.



E se o sistema for público e retornar uma resposta vazia a uma solicitação incorreta, isso é ruim. Porque o desenvolvedor de outro sistema vai consertar na requisição, mas pela resposta vazia ele nem vai entender onde exatamente. E vai incomodar o apoio: "O que há de errado comigo?", Jogando informações peça por peça e na forma de capturas de tela do código-fonte. Você precisa disso? Não? Em seguida, certifique-se de que o sistema apresenta uma mensagem de erro clara!



Consulte também:



O que é XML XML

Tutorial

Aprenda XML. Eric Ray (livro XML)

Notas sobre XML e XLST



PS - para artigos mais úteis, olhe meu blog com a tag "útil" . E vídeos úteis estão no meu canal do youtube