streamalism.org

1. Bemutatkozás

Ebben az oktatóanyagban felfedezzük Az OData, egy szabványos protokoll, amely egyszerű hozzáférést tesz lehetővé az RESTFul API-t használó adatkészletekhez.

2. Mi az OData?

Az OData egy OASIS és ISO / IEC szabvány az adatok RESTful API-val történő eléréséhez. Mint ilyen, lehetővé teszi a fogyasztó számára, hogy szabványos HTTP-hívások segítségével fedezze fel és haladjon végig az adatsorokon.

Például egyszerűen hozzáférhetünk a nyilvánosan elérhető OData szolgáltatások egyikéhez becsavar egysoros:

curl -s //services.odata.org/V2/Northwind/Northwind.svc/Regions Regions //services.odata.org/V2/Northwind/Northwind.svc/Regions ... Az xml többi része kihagy

Az írás kezdetén az OData protokoll 4. verziója van - pontosabban a 4.01. Az OData V4 2014-ben elérte az OASIS szabvány szintjét, de hosszabb múltra tekint vissza. Gyökereit egy Astoria nevű Microsoft projektre vezethetjük vissza, amelyet 2007-ben ADO.Net Data Services névre kereszteltünk. A projektet bejelentő eredeti blogbejegyzés továbbra is elérhető a Microsoft OData blogjában.

Az adatkészletek eléréséhez szabványalapú protokoll megléte bizonyos előnyökkel jár a szokásos API-kkal, például a JDBC-vel vagy az ODBC-vel szemben. Végfelhasználói szintű fogyasztóként olyan népszerű eszközöket használhatunk, mint az Excel, hogy bármilyen kompatibilis szolgáltatótól lehívjuk az adatokat. A programozást számos elérhető REST kliens könyvtár is megkönnyíti.

Szolgáltatóként az OData elfogadásának előnyei is vannak: amint létrehoztunk egy kompatibilis szolgáltatást, arra összpontosíthatunk, hogy értékes adatkészleteket nyújtsunk, amelyeket a végfelhasználók az általuk választott eszközökkel fogyaszthatnak. Mivel HTTP alapú protokollról van szó, olyan szempontokat is felhasználhatunk, mint a biztonsági mechanizmusok, a figyelés és a naplózás.

Ezek a jellemzők tették az OData-t a kormányzati szervek által kedvelt választássá a nyilvános adatszolgáltatások megvalósításakor, mivel ezt ellenőrizhetjük, ha megnézzük ezt a könyvtárat.

3. OData fogalmak

Az OData protokoll lényege egy entitás adatmodell - röviden EDM - fogalma. Az EDM leírja az OData-szolgáltató által kitett adatokat egy metaadat-dokumentumon keresztül, amely számos meta-entitást tartalmaz:

• Az entitás típusa és tulajdonságai (pl. Személy, Vevő, Rendelésstb.) és kulcsokat
• Az entitások közötti kapcsolatok
• Az entitásokba ágyazott strukturált típusok leírására használt komplex típusok (például egy címtípus, amely az a része Vevő típus)
• Entitáskészletek, amelyek egy adott típusú entitásokat összesítenek

A specifikáció előírja, hogy ennek a metaadat-dokumentumnak elérhetőnek kell lennie a szokásos helyen $ metaadatok a szolgáltatás eléréséhez használt root URL-nél. Például, ha van elérhető OData szolgáltatásunk a következő címen: //example.org/odata.svc/, akkor metaadat-dokumentuma elérhető lesz a címen //example.org/odata.svc/$metadata.

A visszaküldött dokumentum egy csomó XML-t tartalmaz, amely leírja a szerver által támogatott sémákat:

   ... a sémaelemek kihagyva 

Bontsuk szét ezt a dokumentumot a fő szakaszaiba.

A legfelső szintű elem, csak egy gyermeke lehet, az elem.A legfontosabb dolog, amit itt észre kell venni, a névtér URI, mivel ez lehetővé teszi számunkra, hogy azonosítsuk, melyik OData verziót használja a szerver. Ebben az esetben a névtér azt jelzi, hogy van egy OData V2 szerverünk, amely a Microsoft azonosítóit használja.

A Adatszolgáltatások elemnek lehet egy vagy több Séma elemek, amelyek mindegyike leír egy elérhető adatkészletet. Mivel a rendelkezésre álló elemek teljes leírása az a Séma meghaladja a cikk kereteit, a legfontosabbakra fogunk összpontosítani: EntityTypes, Egyesületek, és EntitySets.

3.1. EntityType Elem

Ez az elem meghatározza az adott entitás elérhető tulajdonságait, beleértve annak elsődleges kulcsát is. Információt tartalmazhat más sématípusokkal fennálló kapcsolatokról, és egy példa megnézésével - a CarMaker - láthatjuk, hogy ez nem nagyon különbözik a más ORM technológiákban, például a JPA-ban található leírásoktól:

Itt, a mi CarMaker csak két tulajdonsága van - Id és Név - és társulás a másikhoz EntityType. A KulcsokAz ub-elem meghatározza az entitás elsődleges kulcsát Id tulajdon, és mindegyik Ingatlan elem tartalmaz adatokat az entitás tulajdonságairól, például annak nevéről, típusáról vagy érvénytelenségéről.

A NavigationProperty egy speciális típusú tulajdonság, amely egy kapcsolódó entitás „hozzáférési pontját” írja le.

3.2. Egyesület Elem

An Egyesület az elem két entitás közötti asszociációt ír le, amely magában foglalja a két végén lévő sokaságot és adott esetben egy referenciális integritási korlátozást:

Itt a Egyesület elem meghatározza az egy a sokhoz viszonyát a Autómodell és CarMaker jogalanyok, ahol az előbbi függő félként jár el.

3.3. EntitySet Elem

A végső séma koncepció, amelyet megvizsgálunk, a EntitySet elem, amely egy adott típusú entitások gyűjteményét jelenti. Noha könnyű úgy gondolni őket, hogy hasonlítanak egy táblázathoz - és sok esetben csak ilyenek -, a nézet jobb hasonlata. Ennek oka az több is lehet EntitySet elemei ugyanarra EntityType, mindegyik a rendelkezésre álló adatok különböző részhalmazát képviseli.

A EntityContainer elem, amely egy legfelső szintű sémaelem, az összes elérhetőt csoportosítja EntitySets:

Egyszerű példánkban csak kettőnk van EntitySets, de hozzáadhatunk további nézeteket is, például ForeignCarMakers vagy HistoricCarMakers.

4. OData URL-ek és módszerek

Az OData szolgáltatás által kitett adatok eléréséhez a szokásos HTTP igéket használjuk:

• A GET egy vagy több entitást ad vissza
• A POST új entitást ad hozzá egy meglévőhöz Entitáskészlet
• A PUT helyettesít egy adott entitást
• A PATCH egy adott entitás bizonyos tulajdonságait helyettesíti
• A DELETE eltávolítja az adott entitást

Mindezek a műveletek erőforrás-elérési utat igényelnek. Az erőforrás elérési útja meghatározhat egy entitáskészletet, egy entitást vagy akár egy tulajdonságot az entitáson belül.

Nézzünk meg egy példa URL-t, amelyet a korábbi OData szolgáltatásunk eléréséhez használtunk:

//example.org/odata/CarMakers 

Ennek az URL-nek az első része, a protokollig kezdődően a odata / útszakasz, az úgynevezett szolgáltatás gyökér URL-je és ugyanaz a szolgáltatás minden erőforrásútvonalán. Mivel a szolgáltatásgyökér mindig ugyanaz, a következő URL-mintákban ellipszissel („…”) cseréljük ki.

Autó gyártók, ebben az esetben az egyik deklaráltra vonatkozik EntitySets a szolgáltatási metaadatokban. Rendes böngészővel használhatjuk az URL elérését, amelynek vissza kell adnia egy dokumentumot, amely tartalmazza az összes ilyen típusú entitást:

  // 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 ... egyéb bejegyzések kihagyva 

A visszaküldött dokumentum egy belépés elem mindegyikhez CarMaker példa.

Vizsgáljuk meg közelebbről, milyen információk állnak rendelkezésünkre:

• id: link erre a konkrét entitásra
• cím / szerző / frissítve: metaadatok erről a bejegyzésről
• link elemek: Az entitás szerkesztésére használt erőforrásra mutató hivatkozások (rel = ”szerkesztés”) vagy a kapcsolódó szervezetekhez. Ebben az esetben van egy linkünk, amely elvezet minket a halmazhoz Autómodell az adott társult szervezetek CarMaker.
• tartalom: tulajdonságértékei Autómodell entitás

Fontos észrevenni itt a kulcs-érték pár használatát az entitáskészleten belül egy adott entitás azonosítására. Példánkban a kulcs numerikus, tehát az erőforrás útja hasonló CarMaker (1L) olyan entitásra vonatkozik, amelynek elsődleges kulcsértéke 1-vel egyenlő - a „L”Itt csak a-t jelöli hosszú értéket, és el lehet hagyni.

5. Lekérdezési beállítások

A lekérdezési beállításokat átadhatjuk egy erőforrás URL-jének, hogy módosítsuk a visszaküldött adatok számos aspektusát, például korlátozzuk a visszaküldött készlet méretét vagy sorrendjét. Az OData specifikáció gazdag opciókat határoz meg, de itt a leggyakoribbakra koncentrálunk.

Általános szabály, hogy a lekérdezési opciók kombinálhatók egymással, ezáltal lehetővé téve az ügyfelek számára, hogy könnyen megvalósítsák a közös funkciókat, például lapozást, szűrést és az eredménylisták sorrendjét.

5.1. $ top és $ kihagy

Tudunk navigáljon egy nagy adatkészleten a $ top an $ kihagy lekérdezési lehetőségek:

... / Autógyártók? $ Top = 10 & $ skip = 10 

$ top azt mondja a szolgáltatásnak, hogy csak a Autó gyártók entitáskészlet. A $ ugrás, amelyet a $ top, azt mondja a szervernek, hogy hagyja ki az első 10 rekordot.

Általában hasznos tudni az adott méret méretét Entitáskészlet és erre a célra használhatjuk a $ count alerőforrás:

... / CarMakers / $ számít 

Ez az erőforrás a szöveg / sima a megfelelő készlet méretét tartalmazó dokumentum. Itt figyelnünk kell a szolgáltató által támogatott konkrét OData verzióra. Míg az OData V2 támogatja $ count a V4 mint gyűjtemény egy részerõforrása lehetõvé teszi lekérdezési paraméterként való használatát. Ebben az esetben, $ count logikai érték, ezért ennek megfelelően meg kell változtatnunk az URL-t:

... / Autógyártók? $ Count = true 

5.2. $ szűrő

Használjuk a $ szűrő lekérdezési opció korlátozza a visszaküldött entitásokat egy adottból Entitáskészlet azoknak, amelyek megfelelnek az adott kritériumoknak. A. Értéke $ szűrő egy logikai kifejezés, amely támogatja az alapvető operátorokat, a csoportosítást és számos hasznos funkciót. Készítsünk például egy lekérdezést, amely az összeset visszaadja CarMaker olyan esetek, amikor annak Név az attribútum „B” betűvel kezdődik:

... / CarMakers? $ Filter = startswith (név, 'B') 

Most egyesítsünk néhány logikai operátort a kereséshez CarModels egy adott Év és Készítő:

... / CarModels? $ Filter = Év eq 2008 és CarMakerDetails / Név eq 'BWM' 

Itt az egyenlőség operátort használtuk egyenértékű a tulajdonságok értékeinek megadásához. Láthatjuk azt is, hogy miként lehet a kapcsolódó entitás tulajdonságait használni a kifejezésben.

5.3. $ expand

Alapértelmezés szerint egy OData lekérdezés nem ad vissza adatokat a kapcsolódó entitásokhoz, ami általában rendben van. Használhatjuk a $ expand lekérdezési opció annak kérésére, hogy egy adott kapcsolódó entitástól származó adatok szerepeljenek a fő tartalommal együtt.

A mintadomaink segítségével hozzunk létre egy URL-t, amely egy adott modell adatait adja vissza és készítőjével, elkerülve ezzel a szerverhez történő további oda-vissza utat:

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

A visszaküldött dokumentum tartalmazza a CarMaker adatok a kapcsolt entitás részeként:

  //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 Speciális motorok 1 1 Muze SM001 2018 

5.4. $ select

A $ select query opcióval tájékoztatjuk az OData szolgáltatást, hogy csak az adott tulajdonságok értékeit adja vissza. Ez hasznos olyan esetekben, amikor entitásaink nagyszámú tulajdonsággal rendelkeznek, de csak néhányuk érdekel bennünket.

Használjuk ezt az opciót egy olyan lekérdezésben, amely csak a Név és Sku tulajdonságok:

... / CarModels (1L)? $ Select = Név, Sku 

Az így kapott dokumentumnak csak a kért tulajdonságai vannak:

... xml kihagyva Muze SM001 ... xml kihagyva

Azt is láthatjuk, hogy még a kapcsolódó entitásokat is kihagyták. Ahhoz, hogy felvegyük őket, meg kell adnunk a reláció nevét a $ select választási lehetőség.

5.5. $ orderBy

A $ orderBy opció nagyjából úgy működik, mint az SQL megfelelője. Meghatározásra használjuk a sorrend, amelyben azt akarjuk, hogy a szerver adott entitáskészletet adjon vissza. Egyszerűbb formájában az értéke csak a kiválasztott entitás tulajdonságneveinek listája, amely opcionálisan tájékoztatja a rendelés irányát:

... / CarModels? $ OrderBy = Név asc, Sku desc 

Ez a lekérdezés egy listát eredményez CarModels a nevük és a cikkszámuk szerint rendezve, növekvő és csökkenő irányban.

Fontos részlet itt az adott tulajdonság irányrészével használt eset: míg a specifikáció előírja, hogy a szervernek támogatnia kell a kulcsszavak kis- és nagybetűk bármilyen kombinációját asc és desc, Az is felhatalmazza, hogy az ügyfél csak kisbetűket használjon.

5.6. $ formátum

Ez az opció meghatározza a kiszolgáló által használt adatábrázolási formátumot, amely elsőbbséget élvez minden HTTP tartalom-tárgyalási fejlécnél, például Elfogad. Értékének teljes MIME-típusnak vagy formátum-specifikus rövid formának kell lennie.

Például, tudjuk használni json rövidítésként alkalmazás / json:

... / CarModels? $ Format = json 

Ez az URL arra utasítja szolgáltatásunkat, hogy az adatokat XS helyett JSON formátumban adja vissza, amint azt korábban láttuk. Ha ez az opció nincs, a kiszolgáló a Elfogad fejléc, ha van. Ha egyik sem érhető el, a szerver szabadon választhat bármilyen ábrázolást - általában XML vagy JSON.

A JSON-ot illetően alapvetően sémátlan. Az OData 4.01 azonban JSON-sémát határoz meg a metaadatok végpontjaihoz is. Ez azt jelenti, hogy most már írhatunk olyan klienseket, amelyek teljes mértékben megszabadulhatnak az XML-feldolgozástól, ha ezt választják.

6. Következtetés

Az OData ebben a rövid bevezetésében bemutattuk az alapvető szemantikáját és az egyszerű adatkészlet-navigáció végrehajtását. Utánkövető cikkünk ott folytatódik, ahonnan hagytuk, és egyenesen az Olingo könyvtárba megyünk. Ezután meglátjuk, hogyan lehet megvalósítani a mintaszolgáltatásokat e könyvtár használatával.

Kódpéldák, mint mindig, a GitHubon is elérhetők.