Apa itu XML

Jika Anda menguji API, ada dua format transfer data utama yang harus Anda ketahui:

• XML - digunakan dalam permintaan SOAP (selalu) dan REST (lebih jarang) ;
• JSON - digunakan dalam permintaan REST.

Hari ini saya akan memperkenalkan Anda ke XML.



XML , diterjemahkan dari bahasa Inggris e X tensible M arkup L anguage adalah bahasa markup yang dapat diperluas. Digunakan untuk menyimpan dan mengirimkan data. Jadi Anda bisa melihatnya tidak hanya di API, tapi juga di kodenya.



Format ini direkomendasikan oleh World Wide Web Consortium (W3C), sehingga sering digunakan untuk mentransfer data melalui API. Dalam SOAP API, ini biasanya satu-satunya format yang mungkin untuk input dan output data!

Lihat juga:

Apa itu API - pengenalan umum tentang API

Pengenalan SOAP dan REST: apa itu dan apa yang harus dimakan - video tentang perbedaan antara SOAP dan REST.

Jadi, mari kita cari tahu seperti apa bentuknya, cara membacanya, dan cara memecahkannya! Ya, ya, tapi di mana tanpanya? Bagaimanapun, kita perlu mencari tahu bagaimana sistem akan bereaksi terhadap format kurva dari data yang dikirim.

Kandungan

• Bagaimana XML Bekerja
  
  
  • Tag
  • Elemen root
  • Nilai barang
  • Atribut elemen
  • Prolog XML
  • Skema XSD
  • Latihan: menulis permintaan Anda
• XML yang dibentuk dengan baik
  
  
  • 1. Ada elemen root
  • 2. Setiap elemen memiliki tag penutup
  • 3. Tag peka huruf besar / kecil
  • 4. Elemen bersarang yang benar
  • 5. Atribut diapit tanda kutip
• Total

Bagaimana XML Bekerja

Mari kita ambil contoh dari dokumentasi petunjuk nama lengkap Dadata :

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

Dan mari kita cari tahu apa arti entri ini.

Tag

Dalam XML, setiap elemen harus dibungkus dengan tag. Tag adalah beberapa teks yang dibungkus dalam tanda kurung siku:

<tag>

Teks di dalam kurung sudut adalah nama tag.

Selalu ada dua tag:

• Pembuka - teks di dalam tanda kurung sudut

  <tag>

• Menutup - teks yang sama (ini penting!), Tapi simbol "/" ditambahkan

  </tag>

Oh, oke, ketahuan! Tidak selalu. Ada juga elemen kosong, mereka memiliki satu tag, keduanya membuka dan menutup pada saat bersamaan. Tapi lebih dari itu nanti!



Dengan bantuan tag, kami menunjukkan sistem "di sini elemen dimulai, dan ini diakhiri". Ini seperti rambu-rambu jalan:



- Di pintu masuk kota, tertulis namanya: Moskow

- Di pintu keluar, tertulis nama yang sama, tetapi dicoret: Moskow *



* Contoh rambu-rambu jalan yang pernah saya baca beberapa waktu lalu di artikel Yandex, hanya saja saya tidak ingat tautannya. Dan contoh yang sangat bagus!

Elemen root

Setiap dokumen XML memiliki elemen root. Ini adalah tag yang diawali dengan dan diakhiri dengan dokumen. Dalam kasus REST API, dokumen adalah permintaan yang dikirim sistem. Atau jawaban yang didapatnya.



Untuk mewakili permintaan ini, kita membutuhkan elemen root. Di tooltips, elemen root adalah "req".







Ini bisa disebut berbeda:

<main>

<sugg>

Ya terserah. Ini menunjukkan awal dan akhir permintaan kami, tidak lebih. Tapi di dalamnya sudah ada badan dokumen - permintaan itu sendiri. Parameter tersebut yang kami berikan ke sistem eksternal. Tentu saja, mereka juga akan berada di tag, tetapi di tag biasa, bukan di root.

Nilai barang

Nilai elemen disimpan di antara tag awal dan akhir. Ini bisa berupa angka, string, atau bahkan tag bersarang!



Di sini kita memiliki tag "query". Ini menunjukkan permintaan yang kami kirim ke tooltips.







Di dalam - nilai permintaan.







Seolah-olah kita telah mengarahkan baris "Victor Ivan" ke dalam GUI (antarmuka pengguna grafis):







Pengguna tidak memerlukan pengikat ekstra, ia membutuhkan formulir yang cantik. Tetapi sistem entah bagaimana harus menyampaikan bahwa "pengguna memasukkan ini dengan tepat". Bagaimana cara menunjukkan padanya di mana nilai yang diteruskan dimulai dan diakhiri? Itulah gunanya tag.



Sistem melihat tag "query" dan memahami bahwa di dalamnya ada "string yang promptnya harus dikembalikan". Jumlah







parameter = 7menunjukkan berapa banyak petunjuk yang harus dikembalikan dalam tanggapan. Jika Anda memberi tip pada formulir demo Dadata , 7 tip akan kembali kepada kami. Ini karena nilai hitung = 7 dijahit ke dalamnya . Tetapi jika Anda mengacu pada dokumentasi metode , hitungan dapat dipilih dari 1 hingga 20.

Buka konsol pengembang melalui f12 , tab Jaringan , dan lihat permintaan apa yang dikirim ke server. Akan ada hitungan = 7 .







Lihat juga:

Apa yang perlu diketahui penguji tentang panel pengembang - Pelajari lebih lanjut tentang cara menggunakan konsol.

catatan:

• Victor Ivan - string
• 7 - nomor

Tapi kedua nilai itu datang tanpa tanda kutip. Di XML, kita tidak perlu menyertakan nilai string dalam tanda kutip (tapi di JSON, kita harus melakukannya).

Atribut elemen

Sebuah elemen dapat memiliki satu atau lebih atribut. Kami menunjukkannya di dalam tag sobek setelah nama tag dipisahkan oleh spasi di formulir

_ = « »

Misalnya:

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

Mengapa ini dibutuhkan? Dari atribut, sistem yang menerima permintaan API memahami apa yang telah diterimanya sama sekali.



Misalnya, kami melakukan pencarian di sistem, mencari klien dengan nama Oleg. Kami mengirimkan permintaan sederhana:

<query></query>

Dan sebagai gantinya kita mendapatkan satu pak Olegs! Dengan tanggal lahir yang berbeda, nomor telepon dan data lainnya. Misalkan salah satu hasil pencarian terlihat seperti ini:

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

Mari kita lihat entri ini. Kami memiliki pesta elemen utama .







Ini memiliki 3 atribut:

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

Ada elemen lapangan di dalam pesta . Elemen bidang memiliki atribut nama . Nilai atribut adalah nama bidang: nama, tanggal lahir, jenis, atau nomor telepon. Inilah cara kami memahami apa yang tersembunyi di bawah bidang tertentu . Ini nyaman dari sudut pandang dukungan ketika Anda memiliki produk dalam kotak dan 10+ pelanggan. Setiap pelanggan akan memiliki kumpulan bidangnya sendiri: seseorang memiliki INN dalam sistem, seseorang tidak, yang satu penting tentang tanggal lahir, yang lain tidak, dll. Namun, terlepas dari perbedaan model, semua pelanggan akan memiliki satu skema XSD (yang menjelaskan permintaan dan respons): - ada elemen pihak; - memiliki elemen bidang;



























- setiap elemen bidang memiliki atribut nama yang menyimpan nama bidang.



Tetapi nama spesifik dari field tidak lagi dapat dijelaskan di XSD. Mereka sudah "mencari di TK". Tentu saja, jika hanya ada satu pelanggan atau Anda membuat perangkat lunak untuk Anda sendiri atau "secara umum untuk semua orang", akan lebih mudah untuk menggunakan bidang bernama - yaitu, tag "berbicara". Apa keuntungan dari pendekatan ini:



- Saat membaca XSD, bidang nyata segera terlihat. TK mungkin sudah ketinggalan zaman, dan kodenya akan mutakhir

- Permintaan mudah ditarik secara manual di SOAP Ui - itu akan segera membuat semua bidang yang diperlukan, Anda hanya perlu mengisi nilainya. Ini nyaman untuk penguji + pelanggan terkadang menguji seperti ini, dia juga bagus.



Secara umum, setiap pendekatan memiliki hak untuk hidup. Perlu untuk melihat proyek, yang akan lebih nyaman bagi Anda. Dalam contoh saya, saya memiliki nama elemen yang tidak dapat berbicara - semuanya akan menjadi satulapangan . Tapi dengan atributnya Anda sudah bisa mengerti apa itu.



Selain elemen lapangan , partai memiliki elemen atribut . Jangan bingung dengan notasi xml dan bisnis baca:

• dari sudut pandang bisnis, ini adalah atribut dari seorang individu, maka nama elemen - atribut tersebut .
• dari sudut pandang xml itu adalah elemen (bukan atribut!), itu hanya atribut bernama . XML tidak peduli (hampir) bagaimana Anda memberi nama elemen, jadi tidak apa-apa.

The atribut elemen memiliki atribut:

• type = "PHONE" - tipe atribut. Bagaimanapun, mereka bisa berbeda: telepon, alamat, email ...
• rawId = "AL.2.PH.1" - pengenal dalam sistem sumber. Diperlukan untuk memperbarui. Lagi pula, satu klien dapat memiliki beberapa telepon, bagaimana seseorang dapat memahami mana yang sedang diperbarui tanpa ID?

Begitulah XML ternyata. Dan disederhanakan. Dalam sistem nyata di mana individu disimpan, ada lebih banyak data: sekitar 20 bidang individu itu sendiri, beberapa alamat, nomor telepon, alamat email ...



Namun membaca XML yang sangat besar tidak akan sulit jika Anda tahu di mana tempatnya. Dan jika diformat, elemen bertingkat digeser ke kanan, sisanya pada level yang sama. Ini akan sulit tanpa pemformatan ...



Dan semuanya sangat sederhana - kami memiliki elemen yang diapit tag. Di dalam tag adalah nama elemen. Jika ada sesuatu setelah nama, dipisahkan oleh spasi: ini adalah atribut elemen.

Prolog XML

Terkadang di bagian atas dokumen XML Anda akan melihat sesuatu yang serupa:

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

Baris ini disebut prolog XML. Ini menunjukkan versi XML yang digunakan dalam dokumen, serta pengkodeannya. Prolognya opsional, jika tidak ada - tidak apa-apa. Tetapi jika ya, maka itu harus menjadi baris pertama dari dokumen XML.



UTF-8 adalah pengkodean default untuk dokumen XML.

Skema XSD

XSD ( X ML S chema D efinition) adalah deskripsi XML Anda. Bagaimana seharusnya terlihat, bagaimana seharusnya? Ini adalah TK yang ditulis dalam bahasa mesin - lagipula, kami menulis skema ... Juga dalam format XML! Hasilnya adalah XML yang mendeskripsikan XML lain.



Triknya adalah memeriksa sesuai dengan skema dapat didelegasikan ke mesin. Dan pengembang bahkan tidak perlu menjadwalkan setiap pemeriksaan. Cukuplah untuk mengatakan "ini diagram, periksa."



Jika kita membuat metode SOAP, maka kita tunjukkan di skema:

• bidang apa yang akan diminta;
• bidang apa yang akan menjadi tanggapan;
• jenis data apa yang dimiliki setiap bidang;
• bidang mana yang diperlukan dan mana yang tidak;
• Apakah bidang tersebut memiliki nilai default dan apa itu;
• Apakah lapangan memiliki batas panjang?
• Apakah bidang memiliki parameter lain?
• ;
• ...

Sekarang, ketika sebuah permintaan datang kepada kami, pertama kali diperiksa kebenarannya sesuai dengan skema. Jika permintaannya benar, kami meluncurkan metode tersebut dan mengerjakan logika bisnis. Dan itu bisa menjadi kompleks dan intensif sumber daya! Misalnya, buat sampel dari database jutaan dolar. Atau lakukan lusinan pemeriksaan pada tabel database yang berbeda ...



Jadi mengapa menjalankan prosedur yang rumit jika kueri jelas "buruk"? Dan memberikan kesalahan setelah 5 menit, dan tidak langsung? Validasi skema membantu dengan cepat memfilter permintaan yang jelas tidak valid tanpa membebani sistem.







Selain itu, beberapa program klien memberikan perlindungan serupa untuk mengirim permintaan. Misalnya, SOAP Ui dapat memeriksa permintaan Anda untuk format xml yang baik, dan itu tidak akan mengirimkannya ke server jika Anda mengacaukannya. Menghemat waktu saat transfer data, bagus!







Dan untuk pengguna sederhana SOAP API Anda, skema membantu Anda memahami cara membuat permintaan. Apa itu "pengguna sederhana"?

1. Pengembang sistem yang menggunakan API Anda - dia perlu menulis dalam kode apa yang akan dikirim dari sistemnya ke sistem Anda.
2. Seorang penguji yang perlu memeriksa API ini - dia perlu memahami bagaimana permintaan itu terbentuk.

Ya, ya, idealnya kita punya TK yang detil, di mana semuanya dijelaskan dengan baik. Namun sayang dan ah, ini tidak selalu terjadi. Terkadang TK tidak ada, dan terkadang sudah ketinggalan zaman. Tetapi skema tidak akan menjadi usang, karena diperbarui ketika kode diperbarui. Dan itu hanya membantu untuk memahami bagaimana permintaan itu seharusnya terlihat.







Singkatnya, bagaimana skema digunakan saat mengembangkan SOAP API:

• Pengembang kami menulis skema XSD untuk permintaan API: Anda perlu meneruskan elemen ini dan itu, yang akan memiliki turunan ini dan itu, dengan tipe data ini dan itu. Ini wajib, bukan itu.
• Pengembang sistem pelanggan, yang terintegrasi dengan kami, membaca diagram ini dan membangun permintaannya sesuai dengan itu.
• Sistem pelanggan mengirimkan permintaan kepada kami.
• Sistem kami memeriksa permintaan untuk XSD - jika ada yang salah, itu hanya goyangan.
• Jika permintaan XSD lolos verifikasi, aktifkan logika bisnis!

Sekarang mari kita lihat bagaimana rangkaian itu terlihat! Ambil metode doRegister di Pengguna misalnya . Untuk mengirim permintaan, kita harus mengirimkan email, nama dan kata sandi. Ada banyak cara untuk menulis kueri dengan benar dan salah:





Mari kita coba menulis diagram untuk itu. Permintaan harus mengandung 3 elemen ( email, nama, sandi ) berjenis "string" (string). Kami menulis:

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

Dan di WSDl layanan, itu ditulis lebih mudah:

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

Tentu saja, bisa ada lebih dari sekadar elemen sebaris dalam skema. Ini bisa berupa angka, tanggal, nilai boolean, dan bahkan beberapa tipenya sendiri:

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

Anda juga dapat merujuk ke skema lain dalam skema, yang mempermudah penulisan kode - Anda dapat menggunakan kembali skema untuk tugas yang berbeda.



Lihat juga:

XSD - Smart XML - artikel berguna dari Habr

XSD Schema Definition Language - ada tabel yang nyaman dengan nilai yang dapat Anda gunakan

XSD Schema Description Language (XML-Schema)

Contoh skema XML dalam tutorial

Situs resmi w3.org

Latihan: menulis permintaan Anda

Oke, sekarang kita tahu cara "membaca" permintaan untuk metode API dalam format XML. Tapi bagaimana cara menyusunnya menurut TK? Mari mencoba. Kami melihat dokumentasinya. Dan itulah mengapa saya memberikan contoh dari Dadata - ini adalah dokumentasi yang bagus !







Bagaimana jika saya hanya ingin mengembalikan nama lengkap wanita yang diawali dengan "An"? Mari kita ambil contoh asli kita:

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

Pertama-tama, kami mengubah permintaan itu sendiri. Sekarang bukan lagi "Victor Ivan", tapi "An":

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

Selanjutnya, kita lihat TK. Bagaimana cara mengembalikan tip wanita saja? Ada parameter khusus - jenis kelamin . Nama parameter adalah nama tag. Dan kami sudah meletakkan lantai di dalamnya. "Wanita" dalam bahasa Inggris adalah WANITA , juga di dalam dokumentasi. Total diterima:

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

Anda dapat menghapus yang tidak perlu. Jika kita tidak peduli dengan jumlah petunjuk, kita membuang parameter count. Bagaimanapun, menurut dokumentasi, itu opsional. Menerima permintaan:

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

Itu saja! Kami mengambil contoh sebagai dasar, mengubah satu nilai, menambahkan satu parameter, menghapus satu. Tidak sesulit itu. Apalagi bila ada spesifikasi detail dan contoh)))

Cobalah sendiri!

Tulis permintaan untuk metode MagicSearch di Pengguna. Kami ingin menemukan semua Ivanov secara kebetulan, di mana tugas mendesak tergantung.

XML yang dibentuk dengan baik

Terserah pengembang untuk memutuskan XML mana yang benar dan mana yang tidak. Tapi ada aturan umum yang tidak bisa dilanggar. XML harus dibentuk dengan baik, yaitu benar secara sintaksis.



Untuk memeriksa XML untuk sintaks, Anda dapat menggunakan Validator XML apa pun (dan google). Saya merekomendasikan situs w3schools . Ada validator itu sendiri + deskripsi kesalahan umum dengan contoh.



Di validator yang sudah selesai, Anda cukup memasukkan XML Anda (misalnya, permintaan untuk server) dan melihat apakah semuanya baik-baik saja dengannya. Tapi Anda bisa memeriksanya sendiri. Pelajari aturan sintaks dan lihat apakah kueri Anda mengikutinya.



Aturan XML yang dibentuk dengan baik:

1. Ada elemen root.
2. Setiap elemen memiliki tag penutup.
3. Tag peka huruf besar kecil!
4. Elemen bersarang yang benar diamati.
5. Atribut diapit tanda kutip.

Mari kita telusuri setiap aturan dan bahas bagaimana kita dapat menerapkannya dalam pengujian. Yaitu, cara benar "memecah" kueri dengan memeriksanya pada xml yang dibentuk dengan baik. Mengapa ini dibutuhkan? Lihat umpan balik dari sistem. Dapatkah Anda memahami dari teks kesalahan persis di mana Anda mengacaukan?



Lihat juga:

Pesan kesalahan juga merupakan dokumentasi, ujilah! - mengapa menguji pesan kesalahan

1. Ada elemen root

Anda tidak bisa begitu saja meletakkan 2 XML secara berdampingan dan menganggap bahwa "sistem akan mengetahuinya sendiri bahwa ini adalah dua permintaan, bukan satu." Tidak akan mengerti. Karena seharusnya tidak.



Dan jika Anda memiliki beberapa tag berturut-turut tanpa induk yang sama, ini adalah xml yang buruk, format yang tidak baik. Harus selalu ada elemen root:



Apa yang kita lakukan untuk menguji kondisi ini? Benar, kami menghapus tag root dari permintaan kami!

2. Setiap elemen memiliki tag penutup

Semuanya sederhana di sini - jika tag dibuka di suatu tempat, tag itu harus ditutup di suatu tempat. Ingin istirahat? Hapus tag penutup dari setiap elemen.



Tetapi di sini perlu dicatat bahwa mungkin ada satu tag. Jika elemen kosong, kita bisa bertahan dengan satu tag dengan menutupnya di akhir:

<name/>

Ini sama dengan memasukkan nilai kosong di dalamnya

<name></name>

Demikian pula, server dapat mengembalikan nilai tag kosong kepada kami. Anda dapat mencoba mengirim kolom kosong ke Pengguna dengan metode FullUpdateUser . Dan dalam permintaan ini diizinkan (saya mengirim bidang name1 kosong ), dan dalam respons SOAP Ui itu membuat bidang kosong kepada kami persis.







Total - jika ada tag pembuka, harus ada tag penutup. Atau itu akan menjadi satu tag dengan garis miring di akhir.



Untuk pengujian, hapus tag penutup apa pun dalam permintaan.

3. Tag peka huruf besar / kecil

Saat mereka menulis bagian pembukaan - kami juga menulis bagian penutup. SERUPA! Dan bukan seperti yang Anda inginkan.



Tetapi untuk pengujian, kami mengubah register salah satu bagian. XML seperti itu tidak valid

4. Elemen bersarang yang benar

Elemen bisa berpindah satu demi satu.







Satu elemen bisa







bertumpuk di elemen lain Tapi elemen TIDAK bisa saling tumpang tindih!

5. Atribut diapit tanda kutip

Bahkan jika Anda menganggap atribut sebagai angka, itu akan dikutip:

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

Untuk tujuan pengujian, kami mencoba melewatinya tanpa tanda kutip:

<query attr1=123> </query>

Total

XML (e X tensible M arkup L anguage ) digunakan untuk menyimpan dan mentransfer data.

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



— XML . , . XML - , , - .



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

Format XML mengikuti standar. Permintaan yang salah secara sintaksis bahkan tidak akan masuk ke server, klien akan memotongnya. Pertama dibentuk dengan baik, kemudian logika bisnis.



Aturan XML yang dibentuk dengan baik:

1. Ada elemen root.
2. Setiap elemen memiliki tag penutup.
3. Tag peka huruf besar kecil!
4. Elemen bersarang yang benar diamati.
5. Atribut diapit tanda kutip.

Jika Anda seorang penguji, maka saat menguji kueri XML, pastikan untuk mencoba melanggar setiap aturan! Ya, sistem harus dapat menangani kesalahan tersebut dan mengembalikan pesan kesalahan yang memadai. Tapi dia tidak selalu melakukan ini.



Dan jika sistem bersifat publik dan mengembalikan respons kosong untuk permintaan yang salah, ini buruk. Karena pengembang sistem lain akan memperbaikinya dalam permintaan, tetapi dengan jawaban kosong dia bahkan tidak akan mengerti di mana tepatnya. Dan itu akan mengganggu dukungan: "Apa yang salah dengan saya?", Melontarkan informasi sepotong demi sepotong dan dalam bentuk screenshot dari kode sumber. Apakah kamu membutuhkannya? Tidak? Kemudian pastikan sistem memberi Anda pesan kesalahan yang jelas!



Lihat juga:



Apa itu

Tutorial XML XML

Pelajari XML. Eric Ray (Buku XML)

Catatan tentang XML dan XLST



PS - untuk artikel yang lebih bermanfaat, lihat blog saya di bawah tag "berguna" . Dan video yang berguna ada di saluran youtube saya