HTTP: OData v4

Vmesnik OData v4 pod /odata/v4/ – za Access prek gonilnika ODBC, Excel in Power BI prek Power Query ter vsak drug odjemalec OData. Vmesnik bere tabele in poglede, piše posamezne zapise, prek $apply povzema podatke in se sam opisuje v dokumentu metapodatkov.

To je drugi vmesnik nad istim katalogom, namenjen odjemalcem, ki namesto lastnega vmesnika HTTP uporabljajo OData v4: Power Query v Excelu in Power BI ter gonilniku ODBC za OData, prek katerega Access povezuje tabele. Takšen odjemalec vse potrebno izve iz dokumenta metapodatkov in sledi anotacijam protokola; dogovorov lastnega vmesnika HTTP (window, ključ v poizvedbenem nizu) ne pozna. Prijava, pravice, omejevanje hitrosti, revizijska sled in oblika napak so enaki kot pri lastnem vmesniku HTTP (glejte HTTP: oblika napak in HTTP: prijava).

Na PUT prehod odgovori z 405, tako kot pri lastnem vmesniku HTTP.

Katere podatkovne zbirke in sheme lahko klicatelj uporablja, povesta seznama nad koreni storitve. Namenjena sta odjemalcem, ki ponujajo izbiro, na primer pogovornemu oknu za povezavo gonilnika ODBC, podobno kot seznam podatkovnih zbirk v pogovornem oknu SQL Serverja. Gre za navaden dokument storitve po protokolu, katerega vnosi imajo vrsto ServiceDocument – vrsto, ki jo OData predvideva za sklic na drugo storitev (OData JSON Format 4.01, razdelek „Service Document“). Splošni odjemalec jim lahko sledi, ne da bi poznal ta prehod:

{"@odata.context":"https://daten.example.com/odata/v4/$metadata",
 "value":[{"name":"fachdaten","kind":"ServiceDocument","url":"fachdaten/"}]}

Piše se v tabele in poglede, in vedno natanko en zapis. Stavek nastane iz stolpcev kataloga, kot pri lastnem vmesniku; ista pravila veljajo nespremenjeno. Klicatelj določi zapis (prek ključa v naslovu) in vrednosti (prek telesa), nikoli pogoja. Če ključ v naslovu manjka, se zahteva zavrne, namesto da bi zadela celotno množico. Pogled sprejme spremembo, če pravila klicatelja dovoljujejo poglede s to metodo in SQL Server pogled šteje za posodobljivega, tako kot pri gonilniku ODBC za SQL Server, prek katerega Access ureja povezane poglede; če SQL Server spremembo zavrne, prehod odgovori z 422. Stolpce pogleda, ki jih SQL Server ne more posodobiti (skalarna podpoizvedba, izraz, povzetek), prehod označi kot samo za branje (Core.Computed); spremembo, ki navaja enega od njih, zavrne z 400 in imenom stolpca. Izjema so pogledi s sprožilcem INSTEAD OF: tam sprožilec odloča, kaj takšen stolpec pomeni. Access tega podatka ne prevzame: povezan pogled takšen stolpec še naprej ponuja za urejanje, s tem gonilnikom enako kot z ODBC Driver 18 SQL Serverja, in kdor ga spremeni, ob zavrnitvi izgubi tudi druge spremembe zapisa. Kjer uporabniki urejajo podatke v Accessu, zato povežite osnovno tabelo za pisanje, pogled pa le za branje. Lastni vmesnik HTTP (cf) piše samo v tabele.

Vsako pisanje navede zapis prek njegovega celotnega ključa. Edina izjema so odobrene tabele brez ključa: tam klicatelj zapis navede z njegovimi prvotnimi vrednostmi, tudi tedaj pa se spremeni natanko en zapis.

Odgovor je shranjeni zapis z novim ETag; pri ustvarjanju dodatno naslov novega zapisa v glavi Location. Tako klicatelj pozna identitetne ključe, privzete vrednosti in izračunane stolpce, ne da bi moral zapis prebrati znova.

Ključ, ki ga dodeli podatkovna zbirka sama – kot identiteto ali s privzeto vrednostjo, kot je NEWSEQUENTIALID() –, sme pri ustvarjanju manjkati; odgovor in Location navedeta dodeljeno vrednost.

Časovna točka s časovnim pasom se za stolpec brez časovnega pasu preračuna v UTC in shrani kot lokalni čas brez pasu: …T17:00:00Z kot 17.00, …T17:00:00+02:00 kot 15.00. Tu se ne zavrne (drugače kot v lastnem vmesniku HTTP); glejte Časovne točke, števila in imena.

Polja z @ v imenu (@odata.etag, @odata.type) prehod preskoči, namesto da bi jih zavrnil. Odjemalec, ki prebrani zapis pošlje nazaj, jih vključi; niso stolpci.

En koren storitve na alias in shemo. Množica entitet se v OData imenuje kot preprost identifikator, objekti podatkovne zbirke pa so enolični le znotraj sheme. S shemo v korenu se množica imenuje natanko kot objekt (APPARAT), brez ločila, ki bi se lahko pojavilo tudi v pravem imenu.

Dokument metapodatkov velja za vsakega klicatelja posebej. Navede tabele, če sme klicatelj brati tabele aliasa, in poglede, če sme brati poglede – nič, kar bi mu bilo zavrnjeno. Funkcije in procedure se ne pojavijo. Shema brez berljivega objekta, tudi napačno vtipkana, odgovori z 404 in ne s prazno storitvijo.

let
    Quelle = OData.Feed("https://gateway.example.com/odata/v4/fachdaten/dbo/", null,
        [Implementation = "2.0", Headers = [#"X-Api-Key" = "…"]]),
    Apparate = Quelle{[Name = "APPARAT"]}[Data],
    Keller = Table.SelectRows(Apparate, each Text.Contains([Benennung], "Keller"))
in
    Keller

Ključ je zapisan v tem primeru nešifrirano v poizvedbi in s tem v vsaki kopiji delovnega zvezka. To je omejitev prijave prek glave, ne tega vmesnika.

S prijavo Windows glava odpade: OData.Feed("https://gateway.example.com/odata/v4/fachdaten/dbo/", null, [Implementation = "2.0"]), poleg tega v pogovornem oknu za prijavo Power Query način prijave „Windows“.

Ključ. Ključ množice je primarni ključ, če tega ni, pa prvi enolični indeks, vendar le, če noben od njegovih stolpcev ne dovoljuje praznih vrednosti in imajo vsi tip, ki ga protokol dovoljuje kot ključ. Pogled brez lastnega indeksa dobi ključ, ki ga SQL Server navede za njegov rezultat (sp_describe_first_result_set v načinu brskanja, is_part_of_unique_key) , torej isti podatek, iz katerega gonilnik ODBC za SQL Server izpelje ključ pogleda. Ključ se prevzame le, če pogled prikaže vse te stolpce: če mora SQL Server dodati ključni stolpec osnovne tabele, ki ga pogled ne izbere (spoj), vidni stolpci sami ne določajo zapisa. Pogled brez takega ključa je ponujen brez ključa: berljiv in filtriran, vendar posameznega zapisa ni mogoče nasloviti. Protokol ključ sicer pričakuje, vendar bi bili brez te izjeme nedosegljivi prav pogledi, prek katerih naj bi odjemalec bral.

Pogled se opiše po svojem rezultatu, ne po shranjenem seznamu stolpcev. Pogled nad SELECT *, katerega tabele so se medtem spremenile, obdrži stari seznam, dokler nekdo ne izvede sp_refreshview, SQL Server pa nove stolpce vrača pod starimi imeni, zato bi vrednosti prispele pod napačnimi imeni stolpcev in z napačnim tipom. Prehod zato vsak pogled opiše prek sys.dm_exec_describe_first_result_set, kot gonilnik ODBC opiše rezultat, in za vsak pogled enkrat zapiše opozorilo v dnevnik.

Kaj prehod sporoči o podatkovni zbirki. Podatki, ki jih OData ne pozna, odjemalec pa jih potrebuje, da se do aplikacije vede kot gonilnik podatkovne zbirke, so v $metadata zapisani kot anotacije lastnega slovarja. Slovar (imenski prostor Wkl.Store.V1, alias Store) je brez prijave na voljo pod /odata/v4/$vocabulary/Wkl.Store.V1.xml; odjemalec, ki ga ne pozna, anotacije preskoči in ničesar ne izgubi.

Power Query v Excelu za Microsoft 365 razširjeni dokument metapodatkov prebere brez težav.

Vrstice in strani so pomoč pri načrtovanju poizvedb, ne natančno štetje. Access jih pri povezovanju prebere prek SQLStatistics in po njih načrtuje svoje spoje. Brez števila strani Access spoj včasih izvede tako, da vrstice ene tabele išče posamično po ključu, z eno zahtevo za vsako vrstico druge tabele; s številom strani pošlje spoj v enem stavku. Samo število vrstic načrta ne spremeni. Obe števili izhajata iz kataloških pogledov, ki jih SQL Server sproti vzdržuje; njuno branje je ne glede na velikost tabele hitro in ne potrebuje dodatne pravice.

Podatek o ključu Menge(4711) ali Menge(Auftrag=7,Zeile='a') se prebere s slovnico filtra in nato preveri po svoji obliki: natanko ena primerjava enakosti na ključni stolpec, nič drugega. APPARAT(1 or nummer ne 0) je kot izraz veljaven in bi zadel vsako vrstico, zato je zavrnjen z 400.

Tipi in kodirana imena: Časovne točke, števila in imena.

Kaj prikaže Power Query (Excel, OData.Feed z Implementation="2.0"):

Različica vrstice. Če ima tabela različico vrstice, jo vsak zapis vsebuje kot @odata.etag (W/"<Base64>"), posamezen zapis pa še v glavi ETag. Dokument metapodatkov stolpec napove s Core.OptimisticConcurrency. Vrednost je ista, ki jo If-Match sprejme pri pisanju. Za tabele, ki jih urejate, stolpec ni neobvezen: odjemalec, ki želi spremeniti zapis, sicer nima ničesar, na kar bi vezal predpogoj. Gonilnik ODBC za OData zato spreminjanje in brisanje brez različice vrstice zavrne, namesto da bi brez opozorila prepisal spremembo nekoga drugega. Pri tabeli brez različice vrstice njeno vlogo prevzame žig vrstice, če je zanjo vklopljen.

Naslednje strani prehod ponuja po istih pravilih kot nextLink v lastnem vmesniku HTTP, tu kot @odata.nextLink in kot absoluten naslov, kot ga predvideva protokol. Posredniški strežnik pred prehodom mora zato posredovati shemo in gostitelja (X-Forwarded-*); sicer kontekstni naslovi in naslovi naslednjih strani kažejo na gostitelja, ki ga vidi prehod.

Če je množica razvrščena po svojem ključu (brez $orderby klicatelja, ključ iz celih števil, besedila ali uniqueidentifier, izbrani vsi ključni stolpci), se naslednja stran nadaljuje za ključem zadnje vrstice ($skiptoken, na primer ?$skiptoken=3691 ali ?$skiptoken=Auftrag=7,Zeile='a') namesto po številu vrstic ($skip). $skip postane OFFSET … ROWS, SQL Server pa za vsako stran znova prešteje vse prejšnje vrstice, zato vsaka stran traja dlje od prejšnje. S $skiptoken čas na stran ostane enak. Žeton je za odjemalca neprozoren; prehod ga prebere kot podatek o ključu v naslovu in ga pri drugače razvrščeni zahtevi za branje zavrne z 400. V vseh drugih primerih ostane $skip. Decimalni ključ je namenoma izvzet: če bi ga prebrali s slovnico filtra, bi se njegova vrednost lahko zaokrožila.

Velikost strani po želji odjemalca. Brez $top storitev razreže branje na strani nastavljene velikosti (Gateway:Limits:DefaultTop, privzeto 1.000 vrstic). Odjemalec, ki bere ozke vrstice, na primer samo ključe tabele, lahko z glavo Prefer: odata.maxpagesize=10000 zaprosi za večje strani. Storitev velikost uporabi v mejah MaxTop in MaxRows objekta, jo potrdi v glavi Preference-Applied in še naprej ponudi naslednjo stran: za razliko od $top želja branja ne konča. Navedeni $top ima prednost. Gonilnik ODBC velikost zahteva sam, glede na širino izbranih stolpcev.

Naslednje strani se ne štejejo v omejitev zahtev (Gateway:Security:RateLimit), tu enako kot v lastnem vmesniku HTTP. Vsak naslov naslednje strani zato vsebuje možnost wkl-page, kontrolno vrednost, izračunano iz klicatelja, poti, vseh drugih možnosti in časa poteka (15 minut). Ključ zanjo nastane naključno ob zagonu procesa in ga nikoli ne zapusti. Razlog: odjemalec veliko množico bere stran za stranjo, vsaka stran je zahteva, prekinitev sredi branja z 429 pa bi v Accessu pustila nepopolno tabelo s sporočilom „ODBC–call failed“. Zato se šteje le začetek branja. Pravila:

Zaradi wkl-page nobena zahteva ni zavrnjena: neveljavna kontrolna vrednost odpravi le izvzetje; prijavo in pravice prehod pri vsaki strani preveri kot sicer. Možnost se pojavi le v naslovih, ki jih prehod sestavi sam; odjemalec jo nespremenjeno posreduje naprej (ne začne se z $).

Eno odstopanje od protokola in ena dopolnitev izhajata iz vedenja Power Query:

Razširitev tega prehoda, ni del OData. OData za več sprememb v enem koraku predvideva paket $batch s skupinami sprememb; transakcije prek več posameznih zahtev, kot jo pričakujejo aplikacije ODBC, ne pozna. Splošni odjemalec OData te razširitve ne uporablja; namenjena je gonilniku ODBC in programom, ki jo izrecno naslavljajo.

Odjemalec več zahtev združi v transakcijo, tako kot aplikacija prek gonilnika za SQL Server z BeginTrans/CommitTrans/Rollback. Prehod to napove v dokumentu metapodatkov (Store.Transactions na vsebniku entitet, naslov spodaj); gonilnik ODBC transakcije podpira le tedaj.

{ "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…",
  "KeylessWriteTables": [ "dbo.Protokoll" ] }

Oblike vnosov so enake kot pri RowStampTables (schema.tabelle, schema.*, *), prav tako preverjanje ob zagonu. Navedena tabela, ki ima vendarle ključ, se še naprej zapisuje prek ključa in je navedena v dnevniku.

Prek protokola se to zgodi z dvema vezanima dejanjema, ki ju dokument metapodatkov napove samo za sproščene tabele. Odjemalec po tem prepozna, ali je tabela zapisljiva:

POST /odata/v4/fachdaten/dbo/Protokoll/UpdateByOriginal
{ "original": { "Nummer": 2, "Text": "zwei", "Betrag": null, "Aktiv": false },
  "changes":  { "Text": "neu" } }
 
POST /odata/v4/fachdaten/dbo/Protokoll/DeleteByOriginal
{ "original": { … } }

Ime dejanja je lahko zapisano z imenskim prostorom sheme (fachdaten.dbo.UpdateByOriginal), kot ga zapiše protokol. Pravice se preverijo glede na to, kar dejanje dejansko naredi: spreminjanje potrebuje pravico za PATCH, brisanje za DELETE. Pravica samo za ustvarjanje teh dejanj ne omogoči.

Odgovor ob uspehu: 200 z {"value": 1}.

Množico je mogoče brati združeno in povzeto, po OData Data Aggregation 4.0. Razlog je Access: njegov podatkovni stroj prek povezane tabele gonilniku ODBC pošlje SUM, COUNT(Spalte), MIN, MAX, GROUP BY, HAVING, DISTINCT in za standardni odklon SUM(x * x), ne glede na to, kaj gonilnik sporoča o svojih zmožnostih, in ne računa sam, če gonilnik zavrne; poizvedba tedaj ne uspe s sporočilom „ODBC–call failed“. Brez prepustne poti, torej za vsak ključ brez pravice sql, do vsot in skupin vodita $apply in (kjer jih alias sprejema) preverjeni stavki. Gre za branje: veljajo pravice za branje množice, vsota prek milijona vrstic pa se prenese kot eno število.

GET …/Auftrag?$apply=groupby((Werk),aggregate($count as Anzahl,Menge with sum as Summe))
GET …/Auftrag?$apply=filter(Werk eq 3)/aggregate(Menge with average as Mittel)
GET …/Rolle?$apply=groupby((Abteilung),aggregate($count as N))&$filter=N gt 1&$orderby=N desc&$top=10
GET …/Rolle?$apply=compute(Id mul Id as Q)/aggregate(Q with sum as Quadratsumme)
GET …/Rolle?$apply=groupby((Abteilung))                          različne vrednosti (DISTINCT)

{"@odata.context":"…/$metadata#Auftrag(Werk,Anzahl,Summe)",
 "value":[{"Werk":1,"Anzahl":2140,"Summe":18350.5}, …]}

Kaj $apply izvede (v tem vrstnem redu, vsako transformacijo največ enkrat):

Po $apply se ostale možnosti nanašajo na skupine, kot predvideva protokol: $filter je SQL HAVING in sme navesti alias ($filter=N gt 1), $orderby razvrsti skupine, $top, $skip in $count=true jih razdelijo na okna in preštejejo. Navajajo lahko le, kar rezultat vsebuje (lastnost združevanja ali alias); drug stolpec množice prehod zavrne z 400. Brez $orderby so skupine razvrščene po svojih lastnostih združevanja, tako da se zaporedna okna ne prekrivajo.

Dokument metapodatkov napove, kaj se izvede: Aggregation.ApplySupported s štirimi transformacijami in brez Rollup, poleg tega lastno metodo štetja. Gonilnik ODBC združuje le prek prehoda, ki to napove. V lastnem vmesniku HTTP (/api/v1/cf/…) je $apply zavrnjen.

Stavek je izpeljana tabela, iz katere se skupine berejo kot vrstice:

SELECT TOP (100) * FROM (
    SELECT [Kunde], COUNT_BIG(*) AS [Anzahl] FROM [dbo].[Umsatz] WHERE [Nr] > @p0 GROUP BY [Kunde]
) AS [gw_g] WHERE [Anzahl] > @p1 ORDER BY [Anzahl] DESC

Le tako lahko pogoj na skupine navede alias in za okno velja ista logika kot pri navadnem branju. Vrednosti se kot povsod posredujejo kot parametri; števila iz compute prehod zapiše iz prebrane vrednosti, nikoli iz besedila klicatelja.

• HTTP: specifikacija vmesnika · Prijava
• Nalaganje podatkov v Excel s Power Query
• Časovne točke, števila in imena