OData Protocol Guide
1. Introduksjon
I denne opplæringen vil vi utforske OData, en standardprotokoll som gir enkel tilgang til datasett ved hjelp av en RESTFul API.
2. Hva er? OData?
OData er en OASIS- og ISO / IEC-standard for tilgang til data ved hjelp av en RESTful API. Som sådan tillater det en forbruker å oppdage og navigere gjennom datasett ved hjelp av standard HTTP-samtaler.
For eksempel kan vi få tilgang til en av de offentlig tilgjengelige OData-tjenestene med en enkel krølle en-liner:
curl -s //services.odata.org/V2/Northwind/Northwind.svc/Regions Regions //services.odata.org/V2/Northwind/Northwind.svc/Regions ... resten av xml-svar utelattI skrivende stund har OData-protokollen sin fjerde versjon - 4.01 for å være mer presis. OData V4 nådde OASIS-standardnivået i 2014, men det har en lengre historie. Vi kan spore dens røtter til et Microsoft-prosjekt kalt Astoria, som ble omdøpt til ADO.Net Data Services i 2007. Den opprinnelige blogginnlegget som kunngjorde dette prosjektet, er fortsatt tilgjengelig på Microsofts OData-blogg.
Å ha en standardbasert protokoll for å få tilgang til datasett gir noen fordeler i forhold til standard APIer som JDBC eller ODBC. Som sluttbrukernivå kan vi bruke populære verktøy som Excel for å hente data fra en hvilken som helst kompatibel leverandør. Programmering tilrettelegges også av et stort antall tilgjengelige REST-klientbiblioteker.
Som leverandører har adopsjon av OData også fordeler: Når vi har opprettet en kompatibel tjeneste, kan vi fokusere på å tilby verdifulle datasett som sluttbrukere kan konsumere ved hjelp av verktøyene de velger. Siden det er en HTTP-basert protokoll, kan vi også utnytte aspekter som sikkerhetsmekanismer, overvåking og logging.
Disse egenskapene gjorde OData til et populært valg av offentlige etater når vi implementerte offentlige datatjenester, som vi kan sjekke ved å ta en titt på denne katalogen.
3. OData-konsepter
Kjernen i OData-protokollen er konseptet med en enhetsdatamodell - eller kort sagt EDM. EDM beskriver data eksponert av en OData-leverandør gjennom et metadatadokument som inneholder et antall metaenheter:
- Enhetstype og dens egenskaper (f.eks. Person, Kunde, Rekkefølge, etc) og nøkler
- Forhold mellom enheter
- Komplekse typer som brukes til å beskrive strukturerte typer innebygd i enheter (for eksempel en adressetype som er en del av en Kunde type)
- Enhetssett, som samler enheter av en gitt type
Spesifikasjonen foreskriver at dette metadatadokumentet må være tilgjengelig på standardplasseringen $ metadata ved rotnettadressen som brukes til å få tilgang til tjenesten. For eksempel hvis vi har en OData-tjeneste tilgjengelig på //eksempel.org/odata.svc/, vil metadatadokumentet være tilgjengelig på //eksempel.org/odata.svc/$metadata.
Det returnerte dokumentet inneholder en haug med XML som beskriver skjemaene som støttes av denne serveren:
... skjemaelementer utelatt La oss rive ned dette dokumentet i hoveddelene.
Elementet på toppnivå, kan bare ha ett barn, den element.Det som er viktig å legge merke til her er navneområdet URI siden det lar oss identifisere hvilken OData-versjon serveren bruker. I dette tilfellet indikerer navneområdet at vi har en OData V2-server, som bruker Microsofts identifikatorer.
EN DataServices element kan ha en eller flere Skjema elementer, som hver beskriver et tilgjengelig datasett. Siden en fullstendig beskrivelse av tilgjengelige elementer i a Skjema er utenfor omfanget av denne artikkelen, vil vi fokusere på de viktigste: EntityTypes, Associations, og EntitySets.
3.1. EntityType Element
Dette elementet definerer de tilgjengelige egenskapene til en gitt enhet, inkludert dens primære nøkkel. Det kan også inneholde informasjon om forhold til andre skjematyper, og ved å se på et eksempel - a CarMaker - vi kan se at det ikke er veldig forskjellig fra beskrivelser som finnes i andre ORM-teknologier, for eksempel JPA:
Her, vår CarMaker har bare to egenskaper - Id og Navn - og en forening til en annen EntityType. De Nøkkel sub-element definerer enhetens primære nøkkel til å være dens Id eiendom, og hver Eiendom element inneholder data om en enhets eiendom, for eksempel navn, type eller ugyldighet.
EN Navigasjon Eiendom er en spesiell type eiendom som beskriver et “tilgangspunkt” til en beslektet enhet.
3.2. assosiasjon Element
An assosiasjon element beskriver en tilknytning mellom to enheter, som inkluderer mangfoldet i hver ende og eventuelt en referanseintegritetsbegrensning:
Her, den assosiasjon element definerer et en-til-mange forhold mellom en CarModel og CarMaker enheter, der førstnevnte fungerer som den avhengige parten.
3.3. EntitySet Element
Det endelige skjemakonseptet vi skal utforske er EntitySet element, som representerer en samling enheter av en gitt type. Selv om det er lett å tenke dem som analoge med et bord - og i mange tilfeller er de bare det - en bedre analogi er den som er en visning. Årsaken til det er at vi kan ha flere EntitySet elementer for det samme EntityTypehvor hver representerer en annen delmengde av tilgjengelige data.
De EntityContainer element, som er et skjemaelement på toppnivå, grupperer alle tilgjengelige EntitySets:
I vårt enkle eksempel har vi bare to EntitySets, men vi kan også legge til flere visninger, for eksempel ForeignCarMakers eller HistoricCarMakers.
4. OData-nettadresser og -metoder
For å få tilgang til data eksponert av en OData-tjeneste, bruker vi de vanlige HTTP-verbene:
- GET returnerer en eller flere enheter
- POST legger til en ny enhet i en eksisterende Enhetssett
- PUT erstatter en gitt enhet
- PATCH erstatter spesifikke egenskaper for en gitt enhet
- SLETT fjerner en gitt enhet
Alle disse operasjonene krever en ressurssti å handle på. Ressurstien kan definere et enhetssett, en enhet eller til og med en eiendom i en enhet.
La oss ta en titt på et eksempel på en URL som ble brukt til å få tilgang til vår forrige OData-tjeneste:
//eksempel.org/odata/CarMakers Den første delen av denne URL-en, og starter med protokollen opp til odata / stisegment, er kjent som tjenestens rot-URL og er den samme for alle ressursstier for denne tjenesten. Siden tjenestens rot alltid er den samme, erstatter vi den i følgende URL-eksempler med en ellips (“…”).
CarMakers, i dette tilfellet, refererer til en av de erklærte EntitySets i tjenestemetadataene. Vi kan bruke en vanlig nettleser for å få tilgang til denne URL-en, som deretter skal returnere et dokument som inneholder alle eksisterende enheter av denne typen:
// 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 ... andre oppføringer utelatt Det returnerte dokumentet inneholder en inngang element for hver CarMaker forekomst.
La oss se nærmere på hvilken informasjon vi har tilgjengelig for oss:
- id: en lenke til denne spesifikke enheten
- tittel / forfatter / oppdatert: metadata om denne oppføringen
- lenke elementer: Koblinger som brukes til å peke på en ressurs som brukes til å redigere enheten (rel = ”rediger”) eller til relaterte enheter. I dette tilfellet har vi en lenke som tar oss til settet med CarModel enheter knyttet til dette CarMaker.
- innhold: eiendomsverdier av CarModel enhet
Et viktig poeng å merke seg her er bruken av nøkkelverdiparet for å identifisere en bestemt enhet i et enhetssett. I vårt eksempel er nøkkelen numerisk, så en ressurssti som CarMaker (1L) refererer til enheten med en primær nøkkelverdi lik 1 - "L”Her betegner bare en lang verdi og kan utelates.
5. Spørringsalternativer
Vi kan sende søkealternativer til en ressurs-URL for å endre en rekke aspekter av de returnerte dataene, for eksempel for å begrense størrelsen på det returnerte settet eller dets bestilling. OData-spesifikasjonen definerer et rikt utvalg av alternativer, men her vil vi fokusere på de vanligste.
Som en generell regel kan spørringsalternativer kombineres med hverandre, slik at klienter enkelt kan implementere vanlige funksjoner som personsøk, filtrering og bestilling av resultatlister.
5.1. $ topp og $ hopp over
Vi kan naviger gjennom et stort datasett ved hjelp av $ topp en $ hopp over søkealternativer:
... / CarMakers? $ Top = 10 & $ skip = 10 $ topp forteller tjenesten at vi bare vil ha de 10 første postene av CarMakers enhetssett. EN $ hopp over, som påføres før $ topp, ber serveren hoppe over de ti første postene.
Det er vanligvis nyttig å vite størrelsen på et gitt Enhetssett og for dette formålet kan vi bruke $ teller underressurs:
... / CarMakers / $ count Denne ressursen produserer en tekst / vanlig dokument som inneholder størrelsen på det tilsvarende settet. Her må vi ta hensyn til den spesifikke OData-versjonen som støttes av en leverandør. Mens OData V2 støtter $ teller som en underressurs fra en samling, lar V4 den brukes som en spørringsparameter. I dette tilfellet, $ teller er en boolsk, så vi må endre nettadressen deretter:
... / CarMakers? $ Count = true 5.2. $ filter
Vi bruker $ filter søkealternativ til begrense de returnerte enhetene fra en gitt Enhetssett til de som samsvarer med gitte kriterier. Verdien for $ filter er et logisk uttrykk som støtter grunnleggende operatører, gruppering og en rekke nyttige funksjoner. La oss for eksempel bygge et spørsmål som returnerer alt CarMaker tilfeller der det er Navn attributt starter med bokstaven ‘B’:
... / CarMakers? $ Filter = startswith (Name, 'B') La oss nå kombinere noen få logiske operatører å søke etter CarModels av et bestemt År og Maker:
... / CarModels? $ Filter = Year eq 2008 and CarMakerDetails / Name eq 'BWM' Her har vi brukt likhetsoperatøren ekv for å spesifisere verdier for egenskapene. Vi kan også se hvordan du bruker egenskaper fra en relatert enhet i uttrykket.
5.3. $ utvide
Som standard returnerer ikke et OData-spørsmål data for relaterte enheter, som vanligvis er OK. Vi kan bruke $ utvide spørringsalternativ for å be om at data fra en gitt beslektet enhet inkluderes i hovedinnholdet.
La oss bygge en URL som returnerer data fra en gitt modell ved hjelp av vårt domenedom og sin produsent, og dermed unngå en ekstra rundtur til serveren:
... / CarModels (1L)? $ Expand = CarMakerDetails Det returnerte dokumentet inkluderer nå CarMaker data som en del av den relaterte enheten:
//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 Special Motors 1 1 Muze SM001 2018 5.4. $ velg
Vi bruker alternativet $ select for å informere OData-tjenesten om at den bare skal returnere verdiene for de angitte egenskapene. Dette er nyttig i scenarier der enhetene våre har et stort antall eiendommer, men vi er bare interessert i noen av dem.
La oss bruke dette alternativet i et spørsmål som bare returnerer Navn og Sku eiendommer:
... / CarModels (1L)? $ Select = Navn, SKU Det resulterende dokumentet har nå bare de ønskede egenskapene:
... xml utelatt Muze SM001 ... xml utelattVi kan også se at selv relaterte enheter ble utelatt. For å inkludere dem, må vi inkludere navnet på relasjonen i $ velg alternativ.
5.5. $ orderBy
De $ orderBy alternativet fungerer ganske mye som dets SQL-motstykke. Vi bruker den til å spesifisere rekkefølgen vi vil at serveren skal returnere et gitt sett med enheter. I sin enklere form er verdien bare en liste over eiendomsnavn fra den valgte enheten, eventuelt informerer om retningen:
... / CarModels? $ OrderBy = Navn asc, Sku desc Dette spørsmålet vil resultere i en liste over CarModels ordnet etter navn og SKU i henholdsvis stigende og synkende retning.
En viktig detalj her er saken som brukes med retningsdelen av en gitt eiendom: mens spesifikasjonen foreskriver at serveren må støtte enhver kombinasjon av store og små bokstaver for nøkkelordene asc og avd, det også pålegger at klienten kun skal bruke små bokstaver.
5.6. $ format
Dette alternativet definerer datarepresentasjonsformatet som serveren skal bruke, som har forrang over ethvert HTTP-innholdsforhandlingshode, for eksempel Aksepterer. Verdien må være en full MIME-type eller et format-spesifikk kort skjema.
For eksempel, Vi kan bruke json som en forkortelse for søknad / json:
... / CarModels? $ Format = json Denne URL-en instruerer tjenesten vår om å returnere data ved hjelp av JSON-format, i stedet for XML, som vi har sett før. Når dette alternativet ikke er tilstede, vil serveren bruke verdien av Aksepterer topptekst, hvis den er tilstede. Når ingen av disse er tilgjengelige, kan serveren velge hvilken som helst representasjon - vanligvis XML eller JSON.
Når det gjelder JSON spesifikt, er det grunnleggende mal. Imidlertid definerer OData 4.01 også et JSON-skjema for metadataendepunkter. Dette betyr at vi nå kan skrive klienter som kan bli helt kvitt XML-behandling hvis de velger å gjøre det.
6. Konklusjon
I denne korte introduksjonen til OData har vi dekket grunnleggende semantikk og hvordan du utfører enkel datasettnavigering. Oppfølgingsartikkelen vår fortsetter der vi dro og går rett inn i Olingo-biblioteket. Vi får se hvordan vi implementerer eksempler på tjenester ved hjelp av dette biblioteket.
Kodeeksempler, som alltid, er tilgjengelige på GitHub.
