streamalism.org

1. Úvod

V tomto výučbe to preskúmame OData, štandardný protokol, ktorý umožňuje ľahký prístup k súborom údajov pomocou rozhrania RESTFul API.

2. Čo je OData?

OData je norma OASIS a ISO / IEC pre prístup k údajom pomocou rozhrania RESTful API. Umožňuje spotrebiteľovi vyhľadávať a prechádzať súbory údajov pomocou štandardných volaní HTTP.

Napríklad môžeme k jednej z verejne dostupných služieb OData získať jednoduchý prístup zvlnenie jednoradový:

curl -s //services.odata.org/V2/Northwind/Northwind.svc/Regions Regions //services.odata.org/V2/Northwind/Northwind.svc/Regions ... zvyšok odpovede XML bol vynechaný

Od tohto písania je protokol OData vo svojej štvrtej verzii - presnejšie 4,01. OData V4 dosiahla štandardnú úroveň OASIS v roku 2014, má však dlhšiu históriu. Môžeme vystopovať jeho korene v projekte spoločnosti Microsoft s názvom Astoria, ktorý bol v roku 2007 premenovaný na ADO.Net Data Services. Originálny blogový príspevok oznamujúci tento projekt je stále k dispozícii na blogu Microsoft OData.

Protokol založený na štandardoch na prístup k množine údajov prináša určité výhody oproti štandardným rozhraniam API, ako sú JDBC alebo ODBC. Ako spotrebiteľ na úrovni koncového používateľa môžeme na získanie údajov od ľubovoľného kompatibilného poskytovateľa použiť populárne nástroje, ako je napríklad Excel. Programovanie uľahčuje aj veľké množstvo dostupných knižníc klientov REST.

Ako poskytovatelia má prijatie OData aj výhody: po vytvorení kompatibilnej služby sa môžeme sústrediť na poskytovanie cenných súborov údajov, ktoré môžu koncoví používatelia využívať pomocou nástrojov podľa svojho výberu. Pretože sa jedná o protokol založený na HTTP, môžeme využiť aj aspekty, ako sú bezpečnostné mechanizmy, monitorovanie a protokolovanie.

Tieto vlastnosti spôsobili, že OData je obľúbenou voľbou vládnych agentúr pri implementácii verejných dátových služieb, čo môžeme skontrolovať nahliadnutím do tohto adresára.

3. Koncepty OData

Jadrom protokolu OData je koncept dátového modelu entity - alebo skrátene EDM. EDM popisuje údaje vystavené poskytovateľom OData prostredníctvom dokumentu metadát obsahujúceho niekoľko meta-entít:

• Typ entity a jej vlastnosti (napr. Osoba, Zákazník, objednaťatď.) a kľúče
• Vzťahy medzi entitami
• Komplexné typy používané na opis štruktúrovaných typov vložených do entít (napríklad typ adresy, ktorý je súčasťou a Zákazník typ)
• Sady entít, ktoré agregujú entity daného typu

Špecifikácia, že tento dokument metadát musí byť k dispozícii na štandardnom mieste $ metadáta na koreňovej adrese URL použitej na prístup k službe. Napríklad, ak máme k dispozícii službu OData na adrese //example.org/odata.svc/, potom bude jeho dokument s metaúdajmi k dispozícii na //example.org/odata.svc/$metadata.

Vrátený dokument obsahuje veľa XML s popisom schém podporovaných týmto serverom:

   ... prvky schémy vynechané 

Rozoberme tento dokument na jeho hlavné časti.

Prvok najvyššej úrovne, môže mať iba jedno dieťa, element.Dôležitou vecou, ​​ktorú si tu treba všimnúť, je URI menného priestoru, pretože nám umožňuje zistiť, ktorú verziu OData server používa. V takom prípade menný priestor naznačuje, že máme server OData V2, ktorý používa identifikátory spoločnosti Microsoft.

A DataServices prvok môže mať jeden alebo viac Schéma prvky, z ktorých každý popisuje dostupný súbor údajov. Pretože úplný popis dostupných prvkov v a Schéma je nad rámec tohto článku, zameriame sa na tie najdôležitejšie: Typy entít, asociácie, a Sady entít.

3.1. EntityType Element

Tento prvok definuje dostupné vlastnosti danej entity vrátane jej primárneho kľúča. Môže tiež obsahovať informácie o vzťahoch s inými typmi schém a pri pohľade na príklad - a Výrobca automobilov - uvidíme, že sa veľmi nelíši od popisov nájdených v iných technológiách ORM, ako napríklad JPA:

Tu, náš Výrobca automobilov má iba dve vlastnosti - Id a názov - a združenie k inej EntityType. The Key sub-element definuje primárny kľúč entity ako jeho Id majetok a každý Nehnuteľnosť prvok obsahuje údaje o majetku entity, ako je jej názov, typ alebo nullabilita.

A NavigationProperty je špeciálny druh majetku, ktorý popisuje „prístupový bod“ k súvisiacej entite.

3.2. Združenie Element

An Združenie element popisuje asociáciu medzi dvoma entitami, ktorá zahrnuje multiplicitu na každom konci a voliteľne obmedzenie referenčnej integrity:

Tu je Združenie prvok definuje vzťah one-to-many medzi a CarModel a Výrobca automobilov subjekty, kde prvý vystupuje ako závislá strana.

3.3. Sada entít Element

Konečný koncept schémy, ktorú preskúmame, je Sada entít prvok, ktorý predstavuje kolekciu entít daného typu. Aj keď je ľahké ich považovať za analogické s tabuľkou - a v mnohých prípadoch sú to práve oni - lepšou analógiou je pohľad. Dôvod je ten môžeme mať viac Sada entít prvky pre to isté EntityType, pričom každá predstavuje inú podmnožinu dostupných údajov.

The EntityContainer element, ktorý je prvkom schémy najvyššej úrovne, zoskupuje všetky dostupné Sada entíts:

V našom jednoduchom príklade máme iba dve Sada entíts, ale mohli by sme pridať aj ďalšie pohľady, ako napr ForeignCarMakers alebo HistoricCarMakers.

4. OData URL a metódy

Na prístup k údajom vystaveným službou OData používame bežné slovesá HTTP:

• GET vráti jednu alebo viac entít
• POST pridá novú entitu k existujúcej Sada entít
• PUT nahrádza danú entitu
• PATCH nahrádza špecifické vlastnosti danej entity
• DELETE odstráni danú entitu

Všetky tieto operácie si vyžadujú cestu zdroja, aby sa dalo konať. Cesta zdroja môže definovať množinu entít, entitu alebo dokonca vlastnosť v rámci entity.

Pozrime sa na príklad adresy URL použitej na prístup k našej predchádzajúcej službe OData:

//example.org/odata/Automobily 

Prvá časť tejto adresy URL, počínajúc protokolom až po odata / úsek cesty, je známy ako koreňová adresa URL služby a je rovnaká pre všetky cesty zdrojov tejto služby. Pretože koreň služby je vždy rovnaký, v nasledujúcich ukážkach adries URL ho nahradíme elipsou („...“).

Výrobcovia automobilov, v tomto prípade odkazuje na jeden z deklarovaných Sady entít v metaúdajoch služby. Na prístup k tejto adrese URL môžeme použiť bežný prehliadač, ktorý by potom mal vrátiť dokument obsahujúci všetky existujúce entity tohto typu:

  // 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 Špeciálne motory ... ďalšie položky boli vynechané 

Vrátený dokument obsahuje vstup prvok pre každého Výrobca automobilov inštancia.

Pozrime sa podrobnejšie, aké informácie máme k dispozícii:

• id: odkaz na tento konkrétny subjekt
• názov / autor / aktualizované: metadáta o tomto zázname
• odkaz elements: Odkazy používané na smerovanie na zdroj používaný na úpravu entity (rel = ”upraviť”) alebo príbuzným subjektom. V takom prípade máme odkaz, ktorý nás zavedie do množiny CarModel subjekty spojené s týmto konkrétnym Výrobca automobilov.
• obsah: majetkové hodnoty CarModel subjekt

Dôležitým bodom, ktorý si tu treba všimnúť, je použitie páru kľúč - hodnota na identifikáciu konkrétnej entity v množine entít. V našom príklade je kľúč číselný, takže cesta zdroja je ako Výrobca automobilov (1L) označuje entitu s hodnotou primárneho kľúča rovnou 1 - „Ľ”Tu iba označuje a dlho hodnotu a dalo by sa vynechať.

5. Možnosti dotazu

Možnosti dotazu môžeme odovzdať do adresy URL zdroja, aby sme mohli upraviť množstvo aspektov vrátených údajov, napríklad obmedziť veľkosť vrátenej množiny alebo jej usporiadanie. Špecifikácia OData definuje bohatú sadu možností, ale tu sa zameriame na tie najbežnejšie.

Spravidla je možné kombinovať možnosti dotazu navzájom, čo umožňuje klientom ľahko implementovať bežné funkcie, ako je stránkovanie, filtrovanie a objednávanie zoznamov výsledkov.

5.1. $ top a $ preskočiť

Môžeme prechádzať veľkým súborom údajov pomocou $ top an $ preskočiť možnosti dotazu:

... / Výrobcovia automobilov? $ Top = 10 & $ skip = 10 

$ top povie službe, že chceme iba prvých 10 záznamov Výrobcovia automobilov množina entít. A $ preskočiť, ktorý sa uplatňuje pred $ top, povie serveru, aby preskočil prvých 10 záznamov.

Spravidla je užitočné poznať veľkosť daného materiálu Sada entít a na tento účel môžeme použiť $ count čiastkový zdroj:

... / Výrobcovia automobilov / počet dolárov 

Tento zdroj vytvára a text / obyčajný dokument obsahujúci veľkosť zodpovedajúcej množiny. Tu musíme venovať pozornosť konkrétnej verzii OData podporovanej poskytovateľom. Zatiaľ čo OData V2 podporuje $ count V4 ako čiastkový zdroj zo zbierky umožňuje, aby bol použitý ako parameter dopytu. V tomto prípade, $ count je booleovský, takže musíme zodpovedajúcim spôsobom zmeniť adresu URL:

... / Výrobcovia automobilov? $ Count = true 

5.2. $ filter

Používame $ filter možnosť dotazu na obmedziť vrátené entity z daného Sada entít zodpovedajúcim daným kritériám. Hodnota pre $ filter je logický výraz, ktorý podporuje základné operátory, zoskupovanie a množstvo užitočných funkcií. Vytvorme napríklad dotaz, ktorý vráti všetky Výrobca automobilov prípadoch, keď je názov atribút začína písmenom „B“:

... / Výrobcovia automobilov? $ Filter = začína sa (meno, „B“) 

Poďme teraz skombinovať niekoľko logických operátorov, ktoré hľadáme CarModels konkrétneho Rok a Tvorca:

... / CarModels? $ Filter = Year eq 2008 and CarMakerDetails / Name eq 'BWM' 

Tu sme použili operátor rovnosti ekv na zadanie hodnôt pre vlastnosti. Môžeme tiež vidieť, ako vo výraze použiť vlastnosti zo súvisiacej entity.

5.3. $ rozšíriť

V predvolenom nastavení dotaz OData nevracia údaje o súvisiacich entitách, čo je zvyčajne v poriadku. Môžeme použiť $ rozšíriť možnosť dotazu požadovať, aby boli údaje od danej súvisiacej entity zahrnuté v súlade s hlavným obsahom.

Pomocou našej vzorovej domény vytvorme adresu URL, ktorá vracia údaje z daného modelu a jeho tvorca, čím sa zabráni ďalšiemu obratu na server:

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

Vrátený dokument teraz obsahuje Výrobca automobilov údaje ako súčasť prepojeného subjektu:

  //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 Špeciálne motory 1 1 Muze SM001 2018 

5.4. $ vyberte

Pomocou možnosti $ select query informujeme službu OData, že by mala vracať iba hodnoty pre dané vlastnosti. Je to užitočné v scenároch, keď naše entity majú veľké množstvo vlastností, ale zaujímajú nás iba niektoré z nich.

Použime túto možnosť v dotaze, ktorý vráti iba znak názov a Sku vlastnosti:

... / CarModels (1L)? $ Select = meno, sk 

Výsledný dokument má teraz iba požadované vlastnosti:

... xml vynechaný Muze SM001 ... xml vynechaný

Vidíme tiež, že boli vynechané dokonca aj súvisiace entity. Aby sme ich mohli zahrnúť, museli by sme do vzťahu zahrnúť názov vzťahu $ vyberte možnosť.

5.5. $ orderBy

The $ orderBy táto voľba funguje do veľkej miery ako jej náprotivok SQL. Používame ho na špecifikáciu v poradí, v akom chceme, aby server vrátil danú množinu entít. V jednoduchšej podobe je jeho hodnotou iba zoznam mien vlastností od vybranej entity, voliteľne informujúci o smere objednávky:

... / CarModels? $ OrderBy = Name asc, Sku desc 

Výsledkom tohto dopytu bude zoznam CarModels zoradené podľa mien a SKU, vzostupne a zostupne.

Dôležitým detailom je prípad použitý v smerovej časti danej vlastnosti: zatiaľ čo spec vyžaduje, aby server musel pre kľúčové slová podporovať akúkoľvek kombináciu veľkých a malých písmen asc a popis, to tiež mandáty, ktoré klient používa iba malé písmená.

5.6. $ formát

Táto voľba definuje formát reprezentácie údajov, ktorý by mal server používať, ktorý má prednosť pred každou hlavičkou HTTP pre vyjednávanie obsahu, ako je napr. súhlasiť. Jeho hodnota musí byť úplný typ MIME alebo krátky formát podľa konkrétneho formátu.

Napríklad môžeme použiť json ako skratka pre aplikácia / json:

... / CarModels? $ Format = json 

Táto adresa URL dáva našej službe pokyn, aby vrátila údaje vo formáte JSON namiesto XML, ako sme už videli. Ak táto možnosť nie je k dispozícii, použije server hodnotu súhlasiť hlavička, ak je prítomná. Ak ani jeden z nich nie je k dispozícii, server si môže zvoliť ľubovoľné zastúpenie - zvyčajne XML alebo JSON.

Pokiaľ ide konkrétne o JSON, je to v zásade bez schémy. OData 4.01 však definuje schému JSON aj pre koncové body metadát. To znamená, že teraz môžeme písať klientom, ktorí sa môžu úplne zbaviť spracovania XML, ak sa tak rozhodnú.

6. Záver

V tomto krátkom úvode do OData sme sa venovali jeho základnej sémantike a spôsobu vykonávania jednoduchej navigácie v množine údajov. Náš nasledujúci článok bude pokračovať tam, kde sme odišli, a pôjdeme priamo do knižnice Olingo. Potom uvidíme, ako implementovať vzorové služby pomocou tejto knižnice.

Príklady kódov sú ako vždy k dispozícii na GitHub.