Que es XML

Si está probando API, hay dos formatos principales de transferencia de datos que debe conocer:

• XML : se utiliza en solicitudes SOAP (siempre) y REST (con menos frecuencia) ;
• JSON : se utiliza en solicitudes REST.

Hoy les presentaré XML.



XML , traducido del inglés e X tensible M arkup L anguage es un lenguaje de marcado extensible. Se utiliza para almacenar y transferir datos. Entonces puedes verlo no solo en la API, sino también en el código.



Este formato es recomendado por el World Wide Web Consortium (W3C), por lo que a menudo se usa para transferir datos a través de API. En la API de SOAP, este es generalmente el único formato posible para los datos de entrada y salida.

Consulte también:

Qué es una API : una introducción general a la API

Introducción a SOAP y REST: qué es y con qué comer : un video sobre la diferencia entre SOAP y REST.

¡Así que averigüemos cómo se ve, cómo leerlo y cómo romperlo! Sí, sí, pero ¿dónde sin él? Después de todo, necesitamos averiguar cómo reaccionará el sistema al formato de curva de los datos enviados.

Contenido

• Cómo funciona XML
  
  
  • Etiquetas
  • Elemento raíz
  • Valor del ítem
  • Atributos de elementos
  • Prólogo XML
  • Esquema XSD
  • Práctica: escribir tu solicitud
• XML bien formado
  
  
  • 1. Hay un elemento raíz
  • 2. Cada elemento tiene una etiqueta de cierre.
  • 3. Las etiquetas distinguen entre mayúsculas y minúsculas
  • 4. Correcto anidamiento de elementos
  • 5. Los atributos se incluyen entre comillas.
• Total

Cómo funciona XML

Tomemos un ejemplo de la documentación de sugerencias de nombre completo de Dadata :

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

Y averigüemos qué significa esta entrada.

Etiquetas

En XML, cada elemento debe estar envuelto en etiquetas. Una etiqueta es un texto envuelto entre corchetes angulares:

<tag>

El texto dentro de los corchetes angulares es el nombre de la etiqueta.

Siempre hay dos etiquetas:

• Abridor: texto entre corchetes angulares

  <tag>

• Cierre: el mismo texto (¡esto es importante!), Pero se agrega el símbolo "/"

  </tag>

Oh, está bien, ¡me atraparon! No siempre. También hay elementos vacíos, tienen una etiqueta, ambos se abren y cierran al mismo tiempo. ¡Pero más sobre eso más adelante!



Con la ayuda de etiquetas, mostramos al sistema "aquí comienza el elemento y aquí termina". Es como señales de tráfico:



- En la entrada de la ciudad, su nombre está escrito: Moscú

- En la salida, está escrito el mismo nombre, pero tachado: Moscú *



* Un ejemplo con señales de tráfico que leí una vez hace mucho tiempo en un artículo de Yandex, solo que no recuerdo el enlace. ¡Y un excelente ejemplo!

Elemento raíz

Cualquier documento XML tiene un elemento raíz. Esta es la etiqueta desde la que comienza y termina el documento. En el caso de la API REST, un documento es una solicitud que envía el sistema. O la respuesta que recibe.



Para designar esta solicitud, necesitamos un elemento raíz. En la información sobre herramientas, el elemento raíz es "req".







Podría llamarse de otra manera:

<main>

<sugg>

Si, lo que sea. Muestra el principio y el final de nuestra solicitud, nada más. Pero adentro ya está el cuerpo del documento, la solicitud en sí. Esos parámetros que pasamos al sistema externo. Por supuesto, también estarán en etiquetas, pero en etiquetas normales, no en las raíz.

Valor del ítem

El valor del elemento se almacena entre las etiquetas de inicio y finalización. Puede ser un número, una cadena o incluso etiquetas anidadas.



Aquí tenemos la etiqueta "consulta". Denota la solicitud que enviamos a la información sobre herramientas.







Dentro: el valor de la solicitud.







Es como si hubiéramos introducido la línea "Victor Ivan" en la GUI (interfaz gráfica de usuario): el







usuario no necesita correas adicionales, necesita una forma hermosa. Pero el sistema debe transmitir de alguna manera que "el usuario ingresó exactamente esto". ¿Cómo le muestro dónde comienza y termina el valor pasado? Para eso están las etiquetas.



El sistema ve la etiqueta "consulta" y comprende que dentro de ella hay "una cadena para la que se deben devolver las solicitudes". Recuento de







parámetros = 7indica cuántas sugerencias devolver en la respuesta. Si da consejos en el formulario de demostración de Dadata, recibiremos 7 consejos. Esto se debe a que tiene cosido el valor count = 7 . Pero si consulta la documentación del método , el recuento se puede seleccionar de 1 a 20.

Abra la consola del desarrollador a través de f12 , pestaña Red , y vea qué solicitud se envía al servidor. Habrá un recuento = 7 .







Consulte también:

Lo que un evaluador debe saber sobre el panel de desarrolladores : obtenga más información sobre cómo usar la consola.

Nota:

• Victor Ivan - cuerda
• 7 - número

Pero ambos valores vienen sin comillas. En XML, no necesitamos encerrar el valor de la cadena entre comillas (pero en JSON, tenemos que hacerlo).

Atributos de elementos

Un elemento puede tener uno o más atributos. Los indicamos dentro de la etiqueta desprendible después del nombre de la etiqueta separados por un espacio en el formulario

_ = « »

Por ejemplo:

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

¿Por qué es necesario? A partir de los atributos, el sistema que recibe la solicitud de API comprende lo que ha recibido.



Por ejemplo, hacemos una búsqueda en el sistema, buscando clientes con el nombre Oleg. Enviamos una simple solicitud:

<query></query>

¡Y a cambio obtenemos un paquete completo de Olegs! Con distintas fechas de nacimiento, números de teléfono y otros datos. Digamos que uno de los resultados de búsqueda tiene este aspecto:

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

Echemos un vistazo a esta entrada. Tenemos la fiesta del elemento principal .







Tiene 3 atributos:

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

Hay elementos de campo dentro del partido . Los elementos de campo tienen un atributo de nombre . El valor del atributo es el nombre del campo: nombre, fecha de nacimiento, tipo o número de teléfono. Así es como entendemos lo que se esconde bajo un campo específico . Esto es conveniente desde el punto de vista del soporte cuando tiene un producto en caja y más de 10 clientes. Cada cliente tendrá su propio conjunto de campos: alguien tiene un INN en el sistema, alguien no, uno es importante sobre la fecha de nacimiento, otro no, etc. Pero, a pesar de la diferencia en los modelos, todos los clientes tendrán un esquema XSD (que describe la solicitud y la respuesta): - hay un elemento de fiesta; - tiene elementos de campo;



























- cada elemento de campo tiene un atributo de nombre que almacena el nombre del campo.



Pero los nombres específicos de los campos ya no se pueden describir en XSD. Ya están "buscar en los conocimientos tradicionales". Por supuesto, cuando solo hay un cliente o está creando software para usted o “en general para todos”, es más conveniente utilizar campos con nombre, es decir, etiquetas de “habla”. ¿Cuáles son las ventajas de este enfoque?



- Al leer XSD, los campos reales son inmediatamente visibles. Los conocimientos tradicionales pueden estar desactualizados y el código estará actualizado.

- La solicitud es fácil de extraer manualmente en SOAP Ui: creará inmediatamente todos los campos necesarios, solo necesita completar los valores. Esto es conveniente para el probador + el cliente a veces prueba así, él también es bueno.



En general, cualquier enfoque tiene derecho a existir. Es necesario mirar el proyecto, que será más conveniente para usted. En mi ejemplo, tengo nombres de elementos que no hablan, todos como uno serácampo . Pero por los atributos ya puedes entender qué es.



Además de los elementos de campo , la fiesta tiene un elemento de atributo . No confunda notación xml y lectura empresarial:

• desde un punto de vista empresarial, este es un atributo de un individuo, de ahí el nombre del elemento - atributo .
• desde el punto de vista de xml es un elemento (¡no un atributo!), simplemente se llamaba atributo . A XML no le importa (casi) cómo se nombran los elementos, así que está bien.

El atributo de elemento tiene atributos:

• type = "PHONE" - tipo de atributo. Después de todo, pueden ser diferentes: teléfono, dirección, correo electrónico ...
• rawId = "AL.2.PH.1" - identificador en el sistema fuente. Es necesario para la actualización. Después de todo, un cliente puede tener varios teléfonos, ¿cómo se puede entender cuál se actualiza sin una identificación?

Así resultó el XML. Y simplificado. En los sistemas reales donde se almacenan los individuos, hay muchos más datos: unos 20 campos del propio individuo, varias direcciones, números de teléfono, direcciones de correo electrónico ...



Pero incluso un XML enorme es fácil de leer si se sabe dónde está. Y si está formateado, los elementos anidados se desplazan hacia la derecha, el resto están al mismo nivel. Será difícil sin formatear ...



Y todo es tan simple: tenemos elementos encerrados en etiquetas. Dentro de las etiquetas está el nombre del elemento. Si hay algo después del nombre, separado por un espacio: estos son los atributos del elemento.

Prólogo XML

A veces, en la parte superior del documento XML, verá algo similar:

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

Esta línea se llama prólogo XML. Muestra la versión de XML utilizada en el documento, así como la codificación. El prólogo es opcional, si no está allí, está bien. Pero si es así, debe ser la primera línea del documento XML.



UTF-8 es la codificación predeterminada para documentos XML.

Esquema XSD

XSD ( X ML S chema D efinition) es su descripción XML. ¿Cómo debería verse, qué debería ser? Esto es TK escrito en el lenguaje de la máquina - después de todo, escribimos el esquema ... ¡También en formato XML! El resultado es XML que describe otro XML.



El truco es que la verificación según el esquema se puede delegar en la máquina. Y el desarrollador ni siquiera tiene que programar cada verificación. Basta decir "aquí hay un diagrama, compruébalo".



Si creamos un método SOAP, entonces indicamos en el esquema:

• qué campos estarán en la solicitud;
• qué campos estarán en la respuesta;
• qué tipo de datos tiene cada campo;
• qué campos son obligatorios y cuáles no;
• ¿Tiene el campo un valor predeterminado y cuál es?
• ¿El campo tiene un límite de longitud?
• ¿Tiene el campo otros parámetros?
• ;
• ...

Ahora, cuando nos llega una solicitud, primero se verifica que sea correcta de acuerdo con el esquema. Si la solicitud es correcta, iniciamos el método y elaboramos la lógica empresarial. ¡Y puede ser complejo y requerir muchos recursos! Por ejemplo, haga una muestra de una base de datos de varios millones de dólares. O realizar una docena de controles en diferentes tablas de bases de datos ...



Entonces, ¿por qué ejecutar un procedimiento complejo si la consulta es obviamente "mala"? ¿Y da un error después de 5 minutos, y no inmediatamente? La validación del esquema ayuda a filtrar rápidamente las solicitudes obviamente inválidas sin sobrecargar el sistema.







Además, algunos programas cliente ofrecen una protección similar para enviar solicitudes. Por ejemplo, SOAP Ui puede verificar su solicitud de xml bien formado, y simplemente no lo enviará al servidor si lo arruinó. Ahorra tiempo en la transferencia de datos, ¡bien hecho!







Y para el usuario simple de su API SOAP, el esquema lo ayuda a comprender cómo redactar una solicitud. ¿Qué es un "usuario simple"?

1. El desarrollador del sistema que usa su API, debe escribir en el código qué enviar exactamente desde su sistema al suyo.
2. Un evaluador que necesita verificar esta misma API, debe comprender cómo se forma la solicitud.

Sí, sí, idealmente tenemos un TK detallado, donde todo está bien descrito. Pero, ay y ah, este no es siempre el caso. A veces, los conocimientos tradicionales simplemente no existen y, a veces, están desactualizados. Pero el esquema no quedará obsoleto, porque se actualiza cuando se actualiza el código. Y solo ayuda a comprender cómo debería verse la solicitud.







En resumen, cómo se usa el esquema al desarrollar la API SOAP:

• Nuestro desarrollador escribe un esquema XSD para la solicitud de la API: debe pasar un elemento tal y cual, que tendrá tal o cual hijos, con tal y tal tipo de datos. Estos son obligatorios, esos no.
• El desarrollador del sistema del cliente, que está integrado con el nuestro, lee este diagrama y construye sus solicitudes de acuerdo con él.
• El sistema del cliente nos envía solicitudes.
• Nuestro sistema verifica las solicitudes de XSD; si algo está mal, es solo una sacudida.
• Si la solicitud XSD pasó la verificación, ¡active la lógica empresarial!

¡Ahora veamos cómo se verá el circuito! Tome el método doRegister en Usuarios, por ejemplo . Para enviar una solicitud, debemos pasar correo electrónico, nombre y contraseña. Hay muchas formas de escribir una consulta correctamente o mal:





Intentemos escribir un diagrama para ello. La solicitud debe contener 3 elementos ( correo electrónico, nombre, contraseña ) de tipo "cadena" (cadena). Nosotros escribimos:

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

Y en el WSDl del servicio, está escrito aún más fácil:

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

Por supuesto, un esquema puede contener más que elementos en línea. Estos pueden ser números, fechas, valores booleanos e incluso algunos de sus propios 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>

También puede hacer referencia a otro esquema en un esquema, lo que facilita la escritura de código; puede reutilizar esquemas para diferentes tareas.



Ver también:

XSD - XML ​​inteligente - artículo útil de Habr

XSD Schema Definition Language - hay tablas convenientes con valores que puede usar

XSD Schema Description Language (XML-Schema)

Un ejemplo de un esquema XML en el tutorial

Sitio oficial w3.org

Práctica: escribir tu solicitud

Bien, ahora sabemos cómo "leer" una solicitud de un método API en formato XML. Pero, ¿cómo elaborarlo según los conocimientos tradicionales? Intentemos. Miramos la documentación. Y es por eso que estoy dando un ejemplo de Dadata: ¡es una excelente documentación !







¿Qué pasa si quiero devolver solo los nombres completos de mujeres que comienzan con "An"? Tomemos nuestro ejemplo original:

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

En primer lugar, cambiamos la solicitud en sí. Ahora ya no es "Victor Ivan", sino "An":

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

A continuación, analizamos los conocimientos tradicionales. ¿Cómo devolver solo propinas femeninas? Hay un parámetro especial: el género . El nombre del parámetro es el nombre de las etiquetas. Y ya pusimos el piso adentro. "Mujer" en inglés es FEMENINO , también en la documentación. Total recibido:

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

Puede eliminar lo innecesario. Si no nos importa el número de pistas, descartamos el parámetro de recuento. Después de todo, según la documentación, es opcional. Recibió una solicitud:

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

¡Eso es todo! Tomamos un ejemplo como base, cambiamos un valor, agregamos un parámetro, eliminamos uno. No es tan dificil. Especialmente cuando hay una especificación detallada y un ejemplo)))

¡Inténtalo tú mismo!

Escriba una solicitud para el método MagicSearch en Usuarios. Queremos encontrar a todos los Ivanov por completa coincidencia, de los que dependen las tareas urgentes.

XML bien formado

Depende del desarrollador decidir qué XML es correcto y cuál no. Pero hay reglas generales que no se pueden violar. XML debe estar bien formado, es decir, sintácticamente correcto.



Para comprobar la sintaxis de XML, puede utilizar cualquier validador de XML (y google). Recomiendo el sitio w3schools . Existe el propio validador + una descripción de errores típicos con ejemplos.



En el validador terminado, simplemente inserte su XML (por ejemplo, una solicitud para el servidor) y vea si todo está bien. Pero puedes comprobarlo tú mismo. Revise las reglas de sintaxis y vea si su consulta las sigue.



Reglas XML bien formadas:

1. Hay un elemento raíz.
2. Cada elemento tiene una etiqueta de cierre.
3. ¡Las etiquetas distinguen entre mayúsculas y minúsculas!
4. Se respeta el correcto anidamiento de elementos.
5. Los atributos se incluyen entre comillas.

Repasemos cada regla y analicemos cómo podemos aplicarlas en las pruebas. Es decir, cómo "romper" correctamente una consulta comparándola con un xml bien formado. ¿Por qué es necesario? Mire los comentarios del sistema. ¿Puedes entender por el texto del error exactamente dónde metiste la pata?



Vea también: Los

mensajes de error también son documentación, ¡pruébelos! - por qué probar los mensajes de error

1. Hay un elemento raíz

No puede simplemente poner 2 XML uno al lado del otro y asumir que "el sistema se dará cuenta por sí solo de que se trata de dos solicitudes, no una". No lo entenderé. Porque no deberías.



Y si tiene varias etiquetas seguidas sin un padre común, este es un XML incorrecto, no está bien formado. Siempre debe haber un elemento raíz:



¿Qué estamos haciendo para probar esta condición? Así es, ¡eliminamos las etiquetas raíz de nuestra solicitud!

2. Cada elemento tiene una etiqueta de cierre.

Aquí todo es simple: si una etiqueta se ha abierto en algún lugar, debe cerrarse en algún lugar. ¿Quieres romper? Retire la etiqueta de cierre de cualquier elemento.



Pero aquí vale la pena señalar que puede haber una sola etiqueta. Si el elemento está vacío, podemos arreglárnoslas con una etiqueta cerrándola al final:

<name/>

Esto es lo mismo que pasar un valor vacío en él.

<name></name>

Del mismo modo, el servidor puede devolvernos un valor de etiqueta vacío. Puede intentar enviar campos vacíos a los usuarios en el método FullUpdateUser . Y esto es aceptable en la solicitud (envié el campo name1 vacío ), y en la respuesta SOAP Ui, nos muestra los campos vacíos exactamente.







Total: si hay una etiqueta de apertura, debe haber una etiqueta de cierre. O será una etiqueta con una barra al final.



Para probar, elimine cualquier etiqueta de cierre en la solicitud.

3. Las etiquetas distinguen entre mayúsculas y minúsculas

Como escribieron el de apertura, también escribimos el de cierre. ¡SIMILAR! Y no de la forma que querías.



Pero para probar, cambiamos el registro de una de las partes. Dicho XML no será válido

4. Correcto anidamiento de elementos

Los elementos pueden ir uno tras otro







Un elemento puede estar anidado en otro ¡







Pero los elementos NO pueden superponerse entre sí!

5. Los atributos se incluyen entre comillas.

Incluso si considera que el atributo es un número, se citará:

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

Para fines de prueba, intentamos pasarlo sin comillas:

<query attr1=123> </query>

Total

XML (e X tensible M arkup L anguage) se utiliza para almacenar y transferir datos.

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



— XML . , . XML - , , - .



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

El formato XML sigue los estándares. Una solicitud sintácticamente incorrecta ni siquiera irá al servidor, el cliente la cortará. Bien formado primero, luego lógica empresarial.



Reglas XML bien formadas:

1. Hay un elemento raíz.
2. Cada elemento tiene una etiqueta de cierre.
3. ¡Las etiquetas distinguen entre mayúsculas y minúsculas!
4. Se respeta el correcto anidamiento de elementos.
5. Los atributos se incluyen entre comillas.

Si es un tester, asegúrese de romper todas las reglas cuando pruebe consultas XML. Sí, el sistema debería poder manejar dichos errores y devolver un mensaje de error adecuado. Pero ella no siempre hace esto.



Y si el sistema es público y devuelve una respuesta vacía a una solicitud incorrecta, eso es malo. Porque el desarrollador de otro sistema lo arreglará en la solicitud, y por la respuesta vacía ni siquiera entenderá dónde exactamente. Y molestará al soporte: "¿Qué me pasa?", Lanzando información pieza a pieza y en forma de capturas de pantalla del código fuente. ¿Lo necesitas? ¿No? ¡Entonces asegúrese de que el sistema le dé un mensaje de error claro!



Consulte también:



Qué es XML XML

Tutorial

Learn XML. Eric Ray (XML Book)

Notas sobre XML y XLST



PD: busque más artículos útiles en mi blog con la etiqueta "útil" . Y hay videos útiles en mi canal de youtube.