streamalism.org

1. Uvod

U ovom uputstvu istražit ćemo OData, standardni protokol koji omogućuje jednostavan pristup skupovima podataka pomoću RESTFul API-ja.

2. Što je OData?

OData je OASIS i ISO / IEC standard za pristup podacima pomoću RESTful API-ja. Kao takav, omogućuje potrošaču otkrivanje i kretanje kroz skupove podataka pomoću standardnih HTTP poziva.

Na primjer, jednoj od javno dostupnih OData usluga možemo pristupiti na jednostavan način kovrča jednoslojna:

curl -s //services.odata.org/V2/Northwind/Northwind.svc/Regions Regions //services.odata.org/V2/Northwind/Northwind.svc/Regions ... ostatak xml odgovora izostavljen

Od ovog pisanja, OData protokol je u svojoj četvrtoj verziji - točnije 4.01. OData V4 dosegao je standardnu ​​razinu OASIS-a 2014. godine, ali ima dužu povijest. Njegove korijene možemo pronaći u Microsoftovom projektu pod nazivom Astoria, koji je 2007. preimenovan u ADO.Net Data Services. Izvorni članak na blogu koji najavljuje ovaj projekt i dalje je dostupan na Microsoftovom blogu OData.

Imati protokol zasnovan na standardima za pristup skupu podataka donosi neke prednosti u odnosu na standardne API-je poput JDBC ili ODBC. Kao potrošač na razini krajnjeg korisnika možemo koristiti popularne alate kao što je Excel za dohvaćanje podataka od bilo kojeg kompatibilnog davatelja usluga. Programiranje je također olakšano velikim brojem dostupnih REST klijentskih knjižnica.

Kao pružatelji usluga, usvajanje OData također ima prednosti: kad stvorimo kompatibilnu uslugu, možemo se usredotočiti na pružanje vrijednih skupova podataka koje krajnji korisnici mogu konzumirati koristeći alate po svom izboru. Budući da se radi o protokolu koji se temelji na HTTP-u, također možemo iskoristiti aspekte kao što su sigurnosni mehanizmi, nadzor i zapisivanje.

Te su karakteristike učinile OData popularnim odabirom vladinih agencija kada su implementirale javne podatkovne usluge, što možemo provjeriti uvidom u ovaj direktorij.

3. OData koncepti

U osnovi protokola OData koncept je Entity Data Model - ili skraćeno EDM. EDM opisuje podatke koje je otkrio pružatelj OData podataka kroz dokument s metapodacima koji sadrži brojne meta-entitete:

• Vrsta entiteta i njegova svojstva (npr. Osoba, Kupac, Narudžba, itd.) i tipke
• Odnosi između entiteta
• Složeni tipovi koji se koriste za opisivanje strukturiranih tipova ugrađenih u entitete (recimo, vrsta adrese koja je dio a Kupac tip)
• Skupovi entiteta koji agregiraju entitete datog tipa

Specifikacija nalaže da ovaj dokument s metapodacima mora biti dostupan na standardnom mjestu $ metapodaci na korijenskom URL-u koji se koristi za pristup usluzi. Na primjer, ako imamo uslugu OData dostupnu na //example.org/odata.svc/, tada će njegov dokument s metapodacima biti dostupan na //example.org/odata.svc/$metadata.

Vraćeni dokument sadrži hrpu XML-a koji opisuje sheme podržane od ovog poslužitelja:

   ... izostavljeni elementi sheme 

Razdvojimo ovaj dokument na njegove glavne odjeljke.

Element najviše razine, može imati samo jedno dijete, element.Ovdje je važno primijetiti URI prostora prostora jer nam omogućuje prepoznavanje verzije OData koju poslužitelj koristi. U ovom slučaju, prostor imena označava da imamo OData V2 poslužitelj, koji koristi Microsoftove identifikatore.

A DataServices element može imati jedan ili više Shema elementi koji svaki opisuju dostupni skup podataka. Budući da je puni opis dostupnih elemenata u a Shema izvan okvira ovog članka, usredotočit ćemo se na najvažnije: Vrste entiteta, udruge, i EntitySets.

3.1. Vrsta entiteta Element

Ovaj element definira dostupna svojstva određenog entiteta, uključujući njegov primarni ključ. Također može sadržavati informacije o odnosima s drugim vrstama shema i, gledajući primjer - a CarMaker - moći ćemo vidjeti da se ne razlikuje mnogo od opisa koji se nalaze u drugim ORM tehnologijama, poput JPA:

Evo, naša Proizvođač automobila ima samo dva svojstva - Iskaznica i Ime - i asocijacija na drugoga Vrsta entiteta. The Ključ sub-element definira primarni ključ entiteta kao njegov Iskaznica imovine, i svaki Vlasništvo element sadrži podatke o svojstvu entiteta kao što su njegovo ime, vrsta ili poništavanje.

A NavigationProperty je posebna vrsta svojstva koja opisuje "pristupnu točku" povezanom entitetu.

3.2. Udruživanje Element

An Udruživanje element opisuje povezanost između dva entiteta, koja uključuje mnoštvo na svakom kraju i po želji referentno ograničenje integriteta:

Evo, Udruživanje element definira odnos jedan prema više između a CarModel i Proizvođač automobila entiteta, pri čemu prvi djeluje kao ovisna stranka.

3.3. EntitySet Element

Konačni koncept sheme koji ćemo istražiti je EntitySet element, koji predstavlja zbirku entiteta dane vrste. Iako ih je lako smatrati analognima tablici - a u mnogim su slučajevima upravo to - bolja analogija je ona s pogledom. Razlog tome je taj možemo imati više EntitySet elementi za iste Vrsta entiteta, svaki predstavlja drugačiji podskup dostupnih podataka.

The EntityContainer element, koji je element sheme najviše razine, grupira sve dostupne EntitySets:

U našem jednostavnom primjeru imamo samo dva EntitySets, ali mogli bismo dodati i dodatne poglede, poput Proizvođači stranih automobila ili HistoricCarMakers.

4. OData URL-ovi i metode

Da bismo pristupili podacima koji su izloženi uslugom OData, koristimo uobičajene HTTP glagole:

• GET vraća jedan ili više entiteta
• POST dodaje novi entitet postojećem Skup entiteta
• PUT zamjenjuje zadani entitet
• PATCH zamjenjuje specifična svojstva određenog entiteta
• DELETE uklanja zadani entitet

Sve te operacije zahtijevaju put resursa prema kojem treba djelovati. Put resursa može definirati skup entiteta, entitet ili čak svojstvo unutar entiteta.

Pogledajmo primjer URL-a koji se koristio za pristup našoj prethodnoj usluzi OData:

//example.org/odata/CarMakers 

Prvi dio ovog URL-a, počevši od protokola do odata / segmenta staze, poznat je kao korijenski URL usluge i jednak je za sve putove resursa ove usluge. Budući da je korijen usluge uvijek isti, zamijenit ćemo ga u sljedećim uzorcima URL-a elipsom (“...”).

Proizvođači automobila, u ovom slučaju, odnosi se na jednog od prijavljenih EntitySets u metapodacima usluge. Za pristup ovom URL-u možemo koristiti uobičajeni preglednik, koji bi zatim trebao vratiti dokument koji sadrži sve postojeće entitete ove vrste:

  // localhost: 8080 / odata / CarMakers CarMakers 2019-04-06T17: 51: 33.588-03: 00 // localhost: 8080 / odata / CarMakers (1L) CarMakers 2019-04-06T17: 51: 33.589-03: 00 1 Special Motors ... ostali unosi izostavljeni 

Vraćeni dokument sadrži ulazak element za svaki Proizvođač automobila primjer.

Pogledajmo izbliza koje nam informacije stoje na raspolaganju:

• iskaznica: veza do ovog određenog entiteta
• naslov / autor / ažurirano: metapodaci o ovom unosu
• veza elementi: Veze koje se koriste za usmjeravanje na resurs koji se koristi za uređivanje entiteta (rel = "uredi") ili povezanim entitetima. U ovom slučaju imamo vezu koja nas vodi do skupa CarModel entiteti povezani s ovim određenim Proizvođač automobila.
• sadržaj: vrijednosti svojstva od CarModel entitet

Ovdje je važno primijetiti upotrebu para ključ / vrijednost za identificiranje određenog entiteta unutar skupa entiteta. U našem primjeru ključ je numerički, pa put resursa poput Proizvođač automobila (1L) odnosi se na entitet s vrijednošću primarnog ključa jednakom 1 - "L”Ovdje samo označava a dugo vrijednost i moglo bi se izostaviti.

5. Opcije upita

Možemo proslijediti opcije upita URL-u resursa kako bismo izmijenili brojne aspekte vraćenih podataka, kao što je ograničavanje veličine vraćenog skupa ili njegovog redoslijeda. Specifikacija OData definira bogat skup opcija, ali ovdje ćemo se usredotočiti na najčešće.

Općenito je pravilo da se opcije upita mogu međusobno kombinirati, omogućujući tako klijentima da lako implementiraju uobičajene funkcije kao što su straničenje, filtriranje i naručivanje popisa rezultata.

5.1. $ vrh i $ preskoči

Možemo kretati se velikim skupom podataka koristeći $ vrh an $ preskoči opcije upita:

... / Proizvođači automobila? $ Top = 10 & $ preskoči = 10 

$ vrh kaže službi da želimo samo prvih 10 zapisa o Proizvođači automobila skup entiteta. A $ preskoči, koji se primjenjuje prije $ vrh, govori poslužitelju da preskoči prvih 10 zapisa.

Obično je korisno znati veličinu datog Skup entiteta i, u tu svrhu, možemo koristiti $ count pod-resurs:

... / CarMakers / $ count 

Ovaj resurs daje a tekst / običan dokument koji sadrži veličinu odgovarajućeg skupa. Ovdje moramo obratiti pažnju na određenu OData verziju koju podržava davatelj usluga. Dok OData V2 podržava $ count kao pod-resurs iz zbirke, V4 omogućuje upotrebu kao parametar upita. U ovom slučaju, $ count je logička vrijednost, pa moramo u skladu s tim promijeniti URL:

... / Proizvođači automobila? $ Count = true 

5.2. $ filter

Koristimo $ filter mogućnost upita za ograničiti vraćene entitete iz datog Skup entiteta onima koji odgovaraju zadanim kriterijima. Vrijednost za $ filtar je logičan izraz koji podržava osnovne operatore, grupiranje i brojne korisne funkcije. Na primjer, napravimo upit koji vraća sve Proizvođač automobila slučajevi u kojima je njegov Ime atribut započinje slovom "B":

... / CarMakers? $ Filter = startwith (Ime, 'B') 

Sad, kombinirajmo nekoliko logičkih operatora za traženje CarModels određenog Godina i Tvorac:

... / CarModels? $ Filter = Godina 2008 i CarMakerDetails / Naziv eq 'BWM' 

Ovdje smo koristili operator jednakosti ekv za specificiranje vrijednosti svojstava. Također možemo vidjeti kako u izrazu koristiti svojstva srodnog entiteta.

5.3. $ proširiti

Prema zadanim postavkama OData upit ne vraća podatke za povezane entitete, što je obično u redu. Možemo koristiti $ proširiti opcija upita za zahtjev da se podaci iz datog povezanog entiteta uključe u red s glavnim sadržajem.

Koristeći našu uzorku domene, napravimo URL koji vraća podatke iz određenog modela i svog proizvođača, čime se izbjegava dodatno povratno putovanje do poslužitelja:

... / CarModels (1L)? $ Expand = CarMakerDetails 

Vraćeni dokument sada uključuje Proizvođač automobila podaci kao dio povezanog entiteta:

  //example.org/odata/CarModels(1L) CarModels 2019-04-07T11: 33: 38.467-03: 00 //example.org/odata/CarMakers(1L) CarMakers 2019-04-07T11: 33: 38.492-03 : 00 1 Specijalni motori 1 1 Muze SM001 2018 

5.4. $ select

Opciju upita $ select koristimo da obavijestimo uslugu OData da bi trebala vraćati samo vrijednosti za zadana svojstva. To je korisno u scenarijima gdje naši entiteti imaju velik broj svojstava, ali nas zanimaju samo neka od njih.

Upotrijebimo ovu opciju u upitu koji vraća samo Ime i Sku Svojstva:

... / CarModels (1L)? $ Select = Ime, Šifra 

Dobiveni dokument sada ima samo tražena svojstva:

... xml izostavljen Muze SM001 ... xml izostavljen

Također možemo vidjeti da su izostavljeni čak i povezani entiteti. Da bismo ih uključili, trebali bismo uključiti naziv relacije u $ select opcija.

5.5. $ narudžbaBy

The $ narudžbaBy opcija djeluje gotovo kao njegov SQL kolega. Koristimo ga za određivanje redoslijed kojim želimo da poslužitelj vrati zadani skup entiteta. U svom jednostavnijem obliku, vrijednost je samo popis imena svojstava iz odabranog entiteta, po želji koja navodi smjer narudžbe:

... / CarModels? $ OrderBy = Ime uzlazno, Opis 

Ovaj upit rezultirat će popisom CarModels poredani prema njihovim imenima i SKU-ovima, u uzlaznom i silaznom smjeru.

Ovdje je važan detalj slučaj koji se koristi s dijelom smjera određenog svojstva: dok specifikacija nalaže da poslužitelj mora podržavati bilo koju kombinaciju velikih i malih slova za ključne riječi uzlazno i desc, također nalaže da klijent koristi samo mala slova.

5.6. $ format

Ova opcija definira format predstavljanja podataka koji bi poslužitelj trebao koristiti, a koji ima prednost nad bilo kojim zaglavljem pregovora o sadržaju HTTP, poput Prihvatiti. Njegova vrijednost mora biti puni MIME-tip ili kratki obrazac specifičan za format.

Na primjer, možemo koristiti json kao kratica za aplikacija / json:

... / CarModels? $ Format = json 

Ovaj URL upućuje našu službu da vraća podatke u formatu JSON, umjesto u XML, kao što smo već vidjeli. Kad ova opcija nije prisutna, poslužitelj će upotrijebiti vrijednost Prihvatiti zaglavlje, ako je prisutno. Kada nije dostupno nijedno, poslužitelj može slobodno odabrati bilo koji prikaz - obično XML ili JSON.

Što se tiče JSON-a, on je u osnovi bez sheme. Međutim, OData 4.01 definira JSON shemu i za krajnje točke metapodataka. To znači da sada možemo pisati klijente koji se mogu potpuno riješiti XML obrade ako to odluče.

6. Zaključak

U ovom kratkom uvodu u OData, pokrili smo njezinu osnovnu semantiku i kako izvesti jednostavnu navigaciju kroz skup podataka. Naš sljedeći članak nastavit će se tamo gdje smo krenuli i ići ravno u knjižnicu Olingo. Tada ćemo vidjeti kako implementirati uzorke usluga pomoću ove knjižnice.

Primjeri koda, kao i uvijek, dostupni su na GitHubu.