HTTP: skrbništvo

Skrbniški vmesnik pod /admin/v1/ ponuja skrbniško shrambo kot množice OData in ukaze; aplikacija za upravljanje (Access) in razred VBA DbGwClient temeljita na njem.

S skrbniško shrambo prehod njene tabele ponuja pod /admin/v1/: kot množice OData, ki jih program za upravljanje poveže kot tabele (Access prek gonilnika ODBC tega prehoda, z obrazci, ki jih za tabele tako ali tako ima), in kot ukaze za vse, kar ni sprememba ene vrstice.

Zakaj dve obliki. Kar je seznam, je množica: program za upravljanje zanjo ne potrebuje lastne kode. Kar vrne ključ ali vpliva na več kot eno vrstico, je ukaz: množica, ki jo Access po ustvarjanju prebere znova, bi morala pravkar izdani ključ bodisi znova izdati bodisi izgubiti.

Pripravljeni odjemalci. „Pregled aplikacije WKL Database Gateway Manager in razreda VBA“ (dokumentacija aplikacije za upravljanje) uporablja vse množice in ukaze (prijava s ključem ali računom Windows in z 2FA); „DbGwClient – razred VBA za podatkovni prehod“ (dokumentacija aplikacije za upravljanje) kliče ukaze iz lastnih aplikacij VBA.

Množice. Ustrezajo tabelam shrambe ena proti ena; seznami pravila ali ključa so vrstice podrejene množice s ključem nadrejene vrstice.

Polja za prikaz. Status je besedilo za prikaz, StatusKind ena od petih vrst (ok, warn, bad, info, neutral), po kateri program za upravljanje obarva oznako; besedilo je vedno prikazano, barva nikoli sama. Polja Can… povedo, ali je ukaz za vrstico trenutno mogoč. Prehod jih izračuna ob branju po uri shrambe; so samo za branje (pisanje 400) in niso del različice vrstice, saj se ključ ne spremeni zato, ker mine dan. Prehod jih izračuna sam, ne Access, ker se izraz, kot je IIf(…), v poizvedbi Accessa ne prevede prek gonilnika ODBC, podatkovna mreža v strežniškem načinu pa bi se tedaj vrnila k počasnemu branju prek Accessa.

Vsaka množica ima lastnost Version (osem bajtov SHA-256 prek shranjenih vrednosti vrstice, vključno z zapečatenimi) kot različico vrstice. Kdor spremeni vrstico, ki jo je po branju spremenil nekdo drug, prejme 412; Access prikaže običajno sporočilo o konfliktu pri pisanju. Vrednosti, ki jih množica prikazuje iz druge množice, niso del različice vrstice: število Rules osebe, Holders pravila dostopa, ime Person dodelitve, ključa ali seje. Novo pravilo za osebo ali njeno novo ime zato ne povzroči konflikta pri pisanju v urejanju, ki je v tistem trenutku odprto. Številke so int (Edm.Int32), ne bigint: Access bigint brez svoje možnosti za velika števila prikaže kot besedilo in nato zavrne pogoj, kot je Id = 3. Besedilo filter primerja brez razlikovanja velikih in malih črk, tako kot SQL Server in kot shramba primerja imena.

Skrbništvo bere vrstice in jih šteje, ne združuje pa jih. Možnost $apply zavrne z 400, njegov dokument metapodatkov pa združevanja ne deklarira (Aggregation.ApplySupported manjka). Gonilnik ODBC se po tej deklaraciji odloči, kaj pošlje skrbništvu (prevod v podrobnostih: „Podprti SQL“ v dokumentaciji gonilnika ODBC):

Za štetje uporabite DCount("*", …), ne DCount("stolpec", …): v zahtevo za štetje se pretvori samo COUNT(*), s pogojem ali brez njega.

Največjo vrednost stolpca dobite kot prvo vrstico poizvedbe, razvrščene padajoče. Prek HTTP, na primer z lastnim dostopom HTTP skrbniškega programa: GET /admin/v1/odata/SignInFindings?$select=Id&$orderby=Id desc&$top=1. Pri SignInFindings je to redko potrebno: če želite šteti samo nove ugotovitve, si zapomnite največji prebrani Id in pošljite SignInFindings/$count?$filter=Id gt 4711 (glejte Ugotovitve pravil prijave).

Vsaka sprememba se pred uveljavitvijo preveri. Sprememba je transakcija: primerjava različice, pisanje, vpis v dnevnik sprememb in nato preverjanje celotne vsebine, enako kot pri ponovnem nalaganju, vključno s pravili, ki jih navaja oseba. Če vsebina preverjanja ne opravi, se vse razveljavi, odgovor 422 pa navede vsako napako. Brez tega preverjanja bi bilo napačno zapisano v shrambi pravilo, vsako ponovno nalaganje bi ga zavrnilo, prehod pa bi neopazno ostal pri stari različici, čeprav bi vmesnik sporočil uspeh. Uveljavljena sprememba velja takoj (prehod shrambo znova naloži, ne da bi čakal na PollSeconds). Pri kršitvi omejitve same shrambe (neznan Item, podvojen ključ, podrejeni vnos brez nadrejene vrstice) prehod prav tako odgovori z 422 in sporočilom SQLite.

Dnevnik sprememb. V isti transakciji kot sprememba: čas, klicatelj (Person (Kennung), ime ključa storitve, račun Windows ali Einrichtung), dejanje (insert, update, delete, command), množica ali ukaz, ključ, vrednosti prej in potem kot JSON. Niz povezave in lastnosti povezave se pojavijo le kot „neu gesetzt“ (na novo nastavljen), ključ nikoli. Razveljavljena sprememba ne pusti vnosa, uveljavljena pa ga ima vedno. Podrejeni vnosi, ki se izbrišejo skupaj z nadrejeno vrstico, niso navedeni posamezno.

Pravica. Pravilo mora vir admin navesti izrecno; * ne zadošča, tako kot pri pravici sql. Databases pravila ne omejujejo skrbništva, saj to ne pripada nobenemu viru podatkov. Pravilo za skrbništvo:

{ "Id": "verwaltung", "Resources": [ "admin" ], "Verbs": [ "*" ] }

Z "ReadOnly": true isto pravilo bere skrbništvo in preverja povezave, ne spremeni pa ničesar (na primer za revizijo):

{ "Id": "revision", "Resources": [ "admin" ], "Verbs": [ "*" ], "ReadOnly": true }

V skrbništvo se je mogoče prijaviti z osebnim ključem in računom Windows, s ključem storitve le pri Gateway:Store:RequireAdminTotp = false, in če nobeno pravilo prijave za skrbništvo ne zahteva 2FA (nova shramba tako pravilo vsebuje; sicer 403 „… gehoert zu keiner Person“ (… ne pripada nobeni osebi), ker ključ storitve ne more imeti 2FA), ne pa s prijavo SQL Server: njeno geslo SQL Server preveri na viru podatkov, skrbništvo pa ne pripada nobenemu viru. Osebni ključ, ki je omejen na vire podatkov, skrbništva nikoli ne doseže; ključ samo za branje ga kvečjemu bere. Vsak naslov vmesnika odgovarja samo prek zaščitene povezave: HTTPS, zaupanja vreden posrednik z X-Forwarded-Proto: https ali zahteva z lastnega računalnika. Sicer 403, tudi za enkratno povezavo.

Prvi skrbnik. Skrbništvo doseže le, kogar navaja pravilo z admin. Prvo takšno osebo ustvari ukaz init-admin na strežniku, ne zahteva prek omrežja, glejte Prvi skrbnik in reševanje.

Enkratna povezava. issue-key z "delivery": "link" namesto ključa vrne naslov, veljaven Gateway:Store:PickupMinutes (privzeto 15 minut, glejte konfiguracijo). Stran na tem naslovu ob odprtju prikaže le gumb; šele njegov POST prikaže ključ, enkrat. Tako poštni program ali klepet, ki povezave odpira za predogled, ključa ne prevzame vnaprej. Čakajoči ključ je samo v pomnilniku procesa, nikoli na disku; ponovni zagon odprte povezave razveljavi. Prevzem je zapisan v dnevniku sprememb (Einmal-Link, z izvorom).

<a id=„enkratna-povezava-po-e-posti“></a>Enkratna povezava po pošti. issue-key in enroll-totp z "delivery": "mail" vrneta naslov za vabilo po pošti (person, delivery, link, linkExpiresAt), veljaven mail_link_hours oz. MailLinkHours (privzeto 72 ur). Drugače kot navadna enkratna povezava:

• Noben ključ ne čaka. Shramba hrani nalogo in kontrolno vsoto SHA-256 povezave, ne ključa. Ključ oz. faktor 2FA nastane šele ob prevzemu; do takrat obstoječi faktor osebe ostane nespremenjen. Kopija datoteke shrambe zato ničesar ne odpre.
• Preživi ponovni zagon prehoda.
• Natanko enkrat. Drugo odprtje prikaže „bereits abgeholt am … um …“ (že prevzeto dne … ob …) (410) s prošnjo, naj to sporočijo skrbništvu, če prejemnik tega ni storil sam; potekla ali neznana povezava 404.
• Odgovor brez identifikatorja ključa: ključ obstaja šele po prevzemu; takrat se pojavi v PersonalKeys. expiresAt pred koncem povezave prehod zavrne z 400.
• Dnevnik: izdaja kot ukaz z delivery: mail, prevzem kot issue-key oz. enroll-totp z akterjem Einmal-Link von <Aussteller> in izvorom.
• Če naloge ob prevzemu ni več mogoče izpolniti (oseba odstranjena), stran to prikaže z 409; povezava takrat ostane neporabljena.

{ "person": "Erika Muster", "label": "Excel Bericht", "expiresAt": "2027-03-31T00:00:00Z",
  "readOnly": true, "databases": [ "fachdaten" ], "from": [ "10.0.0.0/8" ], "exceptFrom": [],
  "delivery": "key" }

Za vse množice in ukaze skrbništva:

test-connection. Telo { "dataSource": "fachdaten" }. Odgovor navede dataSource, reachable, elapsedMilliseconds, productVersion, database in login; če vir podatkov ni dosegljiv, še message (sporočilo strežnika v njegovem jeziku), number in failure. Preizkus odpre povezavo enkrat, brez bazena povezav, in sporoči odgovor strežnika; gonilnik podatkovne zbirke povezave pri tem ne poskusi odpreti znova. Samo po napaki 233 („na drugem koncu cevi ni procesa“) jo takoj odpre še enkrat: SQL Server v istem računalniku zavrnjeno prijavo prek Shared Memory ali Named Pipes včasih sporoči tako namesto z 18456. Če strežnik znova odgovori z 233, res ni dosegljiv:

{ "dataSource": "fachdaten", "reachable": false, "elapsedMilliseconds": 7,
  "message": "Login failed for user 'NT SERVICE\\Wkl.Data.Gateway'.", "number": 18456, "failure": "Login" }

number je številka podatkovne zbirke (pri SQL Server številka napake); prazno, če je ni. failure napako razvrsti neodvisno od jezika strežnika; program po njej pojasni vzrok in predlaga rešitev:

Ponudnik, zgrajen za starejšo različico specifikacije vmesnika ponudnika, number in failure ne vrne; ostaneta prazna.

service-account. Brez telesa. Račun, s katerim se vir podatkov s prijavo Windows (Integrated Security) prijavi v podatkovno zbirko – ime, za katero skrbništvo podatkovne zbirke ustvari prijavo:

{ "account": "NT SERVICE\\Wkl.Data.Gateway", "kind": "Virtual",
  "networkAccount": "FIRMA\\SRV-DATEN$", "domain": "FIRMA" }

Kaj SQL Server potrebuje za ta račun, je opisano v Namestitev – napotki.

Ključi na zahtevo. issue-key z "onDemand": true izda ključ, ki miruje, dokler ga skrbništvo ne odobri. activate-key z { "id": "k…", "hours": 4 } ga odobri; nova odobritev nadomesti tekočo. Zavrnjen (400, sporočilo navede razlog) je ključ, ki ne velja na zahtevo, je zaklenjen ali potekel, trajanje nad max_activation_hours in odobritev prek datuma poteka ključa. deactivate-key z { "id": "k…" } jo takoj konča. Oboje je zapisano z akterjem v dnevniku sprememb; odgovor navede activeUntil.

Pravilo prijave v enem koraku. Pravilo velja, takoj ko je shranjeno. Prek množic najprej nastane pravilo in šele nato njegove značilnosti – zavrnitev vmes velja za vse, tudi za tistega, ki ga shranjuje. save-sign-in-rule pravilo in značilnosti zapiše v eni spremembi:

{ "scope": "All", "method": "Any", "effect": "Deny", "label": "außen nur Frank",
  "exceptFrom": [ "10.0.0.0/8" ], "exceptPersons": [ "Frank Mustermann" ] }

Drugi seznami: from, persons, windowsGroups, exceptWindowsGroups, countries, exceptCountries, operators, exceptOperators, clients, exceptClients, hours, exceptHours (pomen v Pravilniku prijave). Operaterje omrežja prehod shrani kot AS s številko, časovna okna pa v izpisani obliki (Mon-Fri postane Mon,Tue,Wed,Thu,Fri 00:00-24:00). mode je Enforce (privzeto) ali Report za pravilo v preizkusu. Časovno omejene izjeme so v exceptions, vsaka s persons, windowsGroups, countries, from, operators, clients, hours, until (UTC) in label:

{ "scope": "Data", "effect": "Deny", "label": "samo Nemčija",
  "exceptCountries": [ "DE" ], "exceptFrom": [ "10.0.0.0/8" ],
  "exceptions": [ { "persons": [ "Frank Mustermann" ], "countries": [ "TH" ],
                    "until": "2026-11-02T00:00:00Z", "label": "dopust" } ] }

Z "id" ukaz nadomesti pravilo z vsemi značilnostmi in izjemami; brez njega ustvari novo. Odgovor { "id" }. Pri neznani osebi ali neznanem pravilu prehod odgovori z 400, pri vsebini, ki bi bila po spremembi neveljavna, z 422; v obeh primerih se nič ne shrani.

Pojasnilo prijave. explain-sign-in z istim pravilnikom kot resnična prijava izračuna, kaj velja za osebo – za vsak način prijave osebe (račun Windows, prijava SQL Server, vsak osebni ključ) in vsak naveden izvor:

{ "person": "Frank Mustermann", "scope": "Data",
  "origins": [ { "name": "Firmennetz", "address": "10.1.2.3" },
               { "name": "Außen", "address": "203.0.113.7" },
               { "name": "Tajska", "address": "203.0.113.7", "country": "TH" },
               { "name": "Unbekannt", "address": null } ] }

Izvor lahko svojo državo navede sam s country; tako lahko vprašate „kaj velja za Franka na Tajskem?“, ne da bi poznali naslov od tam. Brez country prehod državo prebere iz geolokacijske zbirke kot pri resnični prijavi. Prav tako izvor sprejme operator (operater omrežja, AS3320; brez navedbe iz geolokacijske zbirke), client (vrsta programa; brez navedbe neznana) in at (trenutek v UTC; brez navedbe zdaj), na primer { "name": "Sobota z Excelom", "address": "203.0.113.7", "client": "Power Query", "at": "2026-10-24T10:00:00Z" }.

Odgovor za vsak način prijave (ways) vodi celico za vsak izvor z result – allowed, code (potrebna koda 2FA), denied ali stanje, ki učinkuje pred pravilnikom: revoked, expired, rests (ključ na zahtevo miruje), personDisabled, outsideKeyNetworks – in ustrezna pravila (id, version, label, effect, method, scope); floor prikaže spodnjo mejo skrbništva, country državo, po kateri je bila sprejeta odločitev (prazno, če je neznana ali nobeno pravilo ne navaja držav), operator, client in at druge ocenjene signale, tried pravila v preizkusu, ki bi veljala (kot rules; ne vplivajo na result), in spared pravila, ki jih izjema odpravi (id, version, rule, effect, exception, until). id in version imata enaki vrednosti kot v dogodku prijave (glejte Podlaga odločitve); tako lahko preverite, ali pravilo še velja tako kot ob kakšni prejšnji prijavi. Račun Windows se oceni brez svojih skupin, saj jih pozna le resnična prijava; če pravilo navaja skupine, je zraven groupsUnknown. Od 1 do 16 izvorov na klic.

Dnevnik prijav vsako odločitev o prijavi z izvorom zabeleži v datoteki dnevnikov poleg shrambe (nastavitve pod `Gateway:SignInLog`, postopek v Preverjanje vzorcev prijav in njihovega izvora). Prehod zbrane odločitve zapiše enkrat na minuto in ob tem uporabi pravila prijave, zato se prijava v množicah pojavi do minute pozneje. Vse množice so samo za branje. SignInFindings bere shranjene ugotovitve, druge množice se izračunajo ob branju.

Vrednosti. Method: apiKey, personalKey, windows, sqlLogin, none. Outcome: success, refused, challenge (zahteva brez prijavnih podatkov ali vmesni korak prijave Windows; tudi poziv h kodi 2FA), totpSuccess, totpFailure. NetClass: loopback, private (lastno omrežje, RFC 1918, enolični lokalni naslovi IPv6, link-local, 100.64.0.0/10), public, unknown. V SignInHours je Country prazen, kadar država ni znana. Reason (pri refused): notSignedIn, unknownKey, revoked, expired, rests, personDisabled, outsideKeyNetworks, denied, deniedByCountry (vsako zavrnilno pravilo navaja države), noPerson, enrolmentOpen, noFactor, secondFactorMissing, sessionExpired, limit, unprotected (prijava, ki se sprejme le prek zaščitene povezave, je prispela nešifrirana). Presented navaja podano, neznano ime prijave SQL Server, nikoli ključa. Client je vrsta programa iz glave User-Agent (Power Query, WinHTTP, PowerShell, Browser ali prva beseda); brez glave prazno.

Vsak dogodek prijave, ki ga je ocenil pravilnik prijave, v Rules navede pravila, na katerih je temeljila odločitev, v Signals pa signale, po katerih je bila ocenjena – oboje kot besedilo JSON. Dogodek brez veljavnega prvega faktorja (napačen ključ, napačno geslo) pravilnika ne doseže; tam sta obe polji prazni.

Rules je seznam; prazen ([]), če ni veljalo nobeno pravilo. Vsak vnos navaja:

Signals navaja, kar je poleg stolpcev dogodka vplivalo na odločitev:

Postopek, oseba, ključ in izvor so v stolpcih dogodka (Method, Person, KeyId, Origin, NetClass, NetName); Client je trditev programa in odloča le, če kakšno pravilo sprašuje po programu. Enake zavrnitve ene minute dnevnik združi le, če so o njih odločila ista pravila v isti različici. Iščete lahko s contains, na primer $filter=contains(Rules,'"id":"7"') za vse prijave, pri katerih je sodelovalo pravilo 7.

Pravica sign-in-events. Pravilo mora vir navesti dobesedno, poleg admin; niti * niti sam admin je ne podelita. Naslov in oseba posamezne prijave sta osebna podatka; pravica loči tiste, ki vidijo števila in vzorce, od tistih, ki lahko sledijo posameznim osebam. Velja za SignInEvents, za polja oseb v SignInFindings in SignInAdvice ter za `sign-in-profile`. Brez pravice so ta polja prazna, še preden se uporabi filter zahteve; pogoj zanje tedaj ne vrne ničesar.

Ob vsakem zapisu prehod pravila prijave uporabi na novih dogodkih; kar pravilo zazna, shrani kot ugotovitev. Ugotovitev se zapiše enkrat in se nikoli znova ne ovrednoti; navaja pravilo z njegovimi pragovi (RuleVersion) in primerjalno obdobje (BaselineDays), pod katerima je nastala. Isti položaj – pravilo, izvor ali oseba, ura ali dan – da le eno ugotovitev.

Od zadnjega pogleda. Id raste z vsako ugotovitvijo in se nikoli ne uporabi znova. Program si zapomni najvišji prebrani Id in nato z $filter=Id gt 4711 sprašuje le po novem. S pogojem za Id prehod najprej bere najstarejše ujemajoče se ugotovitve; tako program po korakih v celoti prebere tudi več kot 20.000 novih ugotovitev. Brez takega pogoja vrne najnovejše.

Stopnje. act zahteva ukrepanje: vzorec napada ali predan ključ. ask je vredno vprašanja osebi: nekaj je zanjo novo ali neobičajno. Kam prehod sporoča ugotovitve, določa `Gateway:SignInLog:Alerts`.

Pravila za novosti se sprožijo šele, ko je imela oseba v prejšnjih 90 dneh vsaj 5 uspešnih prijav, unusualHour šele od 20; prej bi bilo vse novo. Dnevi in ure se štejejo v časovnem pasu Gateway:SignInLog:TimeZone. Observed je opažena vrednost (država, število, razdalja), Usual so za primerjavo običajne vrednosti osebe. Besedilo ugotovitve nikoli ne navaja osebe.

sign-in-profile pokaže, kaj je za osebo pri prijavi običajno – na primer, da lahko ovrednotite ugotovitev newCountry. Telo:

{ "person": "Frank Mustermann", "days": 365 }

days šteje nazaj od danes, vključno z današnjim dnem, v časovnem pasu Gateway:SignInLog:TimeZone; privzeto 90, dovoljeno od 1 do 3650. Odgovor navede person, days, from, until, total (uspešne prijave) in activeDays ter pod dimensions za vsako značilnost – country, network, operator, client, method, hour (ura od 00 do 23) – vrednosti z value, count, firstDay in lastDay, najpogostejše najprej. Izsek:

{ "person": "Frank Mustermann", "days": 365, "from": "2025-10-21", "until": "2026-10-20",
  "total": 1184, "activeDays": 213,
  "dimensions": { "country": [ { "value": "DE", "count": 1170, "firstDay": "2025-10-21", "lastDay": "2026-10-20" },
                               { "value": "IT", "count": 14, "firstDay": "2026-07-28", "lastDay": "2026-08-08" } ] } }

Upoštevane so le uspešne prijave. Profil izhaja iz dnevnih vrednosti posamezne osebe, ki v datoteki dnevnikov ostanejo dlje od posameznih dogodkov. Zahteva pravico sign-in-events (sicer 403) in vedno velja za natanko eno osebo; seznama po osebah ni. Neznana oseba: 404; days zunaj obsega: 400.

set-geoip-source. Telo:

{ "source": "maxmind", "account": "123456", "licenseKey": "…", "updateDays": 7 }

source je obvezen: none (datoteke le prek upload-geoip), dbip-lite ali maxmind. updateDays od 0 do 90: po toliko dneh prehod datoteke sam prenese znova (0 = le na ukaz); po neuspelem poskusu poskusi znova čez šest ur. licenseKey se shrani zapečaten z glavnim ključem; če ga v telesu ni, ostane shranjeni, "removeLicenseKey": true ga odstrani. maxmind brez številke računa ali licenčnega ključa: 422. Dnevnik sprememb navede le, ali je ključ nastavljen.

update-geoip. Brez telesa. Prenese obe datoteki in ju začne uporabljati brez ponovnega zagona. Odgovor je files, vsak z kind, databaseType, buildDate, bytes, changed, attribution; datoteka z enakim datumom izdelave kot obstoječa ostane nespremenjena (changed: false). Zavrnjeno z 422 in razlogom: vir ni izbran, vir zavrne ali ne dostavi ničesar, datoteka ni uporabna ali prenos že poteka.

upload-geoip. Telo je datoteka sama (.mmdb, .mmdb.gz ali .tar.gz podjetja MaxMind), Content-Type: application/octet-stream. Možnosti poizvedbe: source=dbip-lite|maxmind določi navedbo vira, force=true sprejme tudi starejšo ali enako staro datoteko. Vrsto (City, Asn) prehod prepozna po vsebini. Odgovor je kot en vnos update-geoip. Večja od GeoIp:MaxMegabytes: 429 (LIMIT_EXCEEDED) kot vsako preveliko telo; neuporabna ali starejša od obstoječe: 422.

Navzven prehod pošlje le zahtevo za prenos datotek; naslovi klicateljev strežnika nikoli ne zapustijo.

Dnevnik obremenitve beleži, koliko stane vsaka oblika zahteve (nastavitve pod `Gateway:LoadLog`, postopek v Ugotavljanje, kaj obremenjuje prehod in podatkovno zbirko). Oblika je zahteva brez svojih vrednosti: pot, alias, vrsta, objekt, primerjana polja, razvrstitev in okno, vsaka vrednost zapisana kot ?. Zahteve, ki se razlikujejo le po vrednostih, so ena oblika. Prehod zbrane številke zapiše enkrat na minuto v datoteko dnevnikov, zato se zahteva v množicah pojavi do minute pozneje. Vse množice so samo za branje. LoadFindings bere shranjene namige, druge množice se izračunajo ob branju.

Vrednosti. Path: odata (površina OData), cf (lastni vmesnik HTTP pod /api/v1/cf/), checked (preverjeni stavek), passthrough (stavek s pravico sql), admin (skrbništvo), other (2FA, samopostrežba, prenosi). Kind: read, count, aggregate, call, insert, update, delete, statement, describe (stavek le opisan), service (zahteva brez podatkov: metapodatki, zavrnitev, skrbništvo). Besedilo stavka prehod hrani brez literalov in komentarjev; dolgi seznami vrednosti se strnejo v ?, …. Preskočene vrstice ($skip) se v Text pojavijo le kot stopnja, nikoli s svojim številom: skip=small (pod 1.000), skip=medium (pod 10.000), skip=large (od 10.000 naprej).

Časi in količine. TotalMs je celoten čas zahteve v prehodu, DataMs del od odprtja povezave do podatkovnega vira do zadnje prebrane vrstice, vključno s preklopom na identiteto osebe.

95. percentil (P95Ms) je zgornja meja časovne stopnje, v katero pade (stopnje 5, 10, 25, 50, 100,

250, 500, 1.000, 2.500, 5.000, 10.000, 30.000 ms; nad tem MaxMs). Bytes šteje odgovor pred stiskanjem. Errors šteje odgovore 5xx, Refused odgovore 4xx. Person je ime osebe, brez osebe pa oznaka klicatelja, kot je v revizijski sledi. Vsote časa, vrstic in bajtov so števila s plavajočo vejico, da program, kot je Access, ki cela števila bere kot 32-bitna, ne prekorači obsega.

Namigi (LoadAdvice). Vsaka koda je vzorec, ki obremenjuje podatkovno zbirko ne glede na podatke:

Pravica load-persons. Pravilo mora vir navesti dobesedno, poleg admin; niti * niti sam admin je ne podelita. Obremenitev po osebah kaže, kdo je kdaj koliko delal; pravica loči tiste, ki vidijo obremenitev prehoda, od tistih, ki lahko primerjajo osebe.

export-load. Telo ni obvezno:

{ "days": 30 }

days od 1 do HourDays, privzeto 30. Odgovor je datoteka JSON wkl-load-LLLLMMDD-hhmmss.json v obliki wkl-load-export/1 s shapes, hours, advice in mejami časovnih stopenj (histogramBounds). Vsebuje imena aliasov, objektov in stolpcev, ne pa oseb, ključev, naslovov, korelacijskih oznak in vrednosti; dnevne številke po osebah in posamezne počasne zahteve se zanjo sploh ne berejo. Potrebna je pravica branja skrbništva; izvoz se zabeleži v dnevniku sprememb.

Prehod vsak stavek, ki ga ustvari sam, označi z oznako njegove oblike kot komentarjem za prvo ključno besedo, na primer SELECT /* wkl:5b9b83f10953 */ TOP (1) … ali UPDATE /* wkl:8b7d7b280081 */ [dbo].[Probe] SET …. Na tem mestu komentar ohrani tudi Query Store, ki komentarja pred stavkom ali za njim ne shrani. Pri klicu procedure stoji oznaka pred klicem; Query Store tedaj zabeleži stavke procedure brez oznake. S to oznako skrbnik podatkovne zbirke najde obliko v predpomnilniku načrtov, v Query Store ali v Extended Events in od tam pride do LoadShapes. Preverjeni stavki prav tako nosijo oznako; stavek s pravico sql se izvede nespremenjen, brez oznake. Povezave se SQL Serverju predstavijo kot Wkl.Data.Gateway (program_name), razen če niz povezave podatkovnega vira nastavi lastno Application Name.

Modul za posodobitve v storitvi namešča podpisane posodobitve podatkovnih zbirk (pakete <izdelek>-schema-<različica>.zip) v podatkovne zbirke, za katere ima mapa `Gateway:Updates` zaščiteno konfiguracijo. Na vsakih PollSeconds sekund preveri pakete v vhodni mapi, katerih kopiranje se je končalo vsaj pred 5 sekundami, in napovedane pakete, katerih rok je potekel. Ukazi prikažejo stanje in izvedejo odločitve skrbnikov.

Pravice. update-databases, update-status in update-history berejo (zadošča pravilo z admin, tudi samo za branje). Vsaka odločitev potrebuje pravico za spreminjanje in se zapiše v dnevnik sprememb s podatkovno zbirko, paketom in izidom.

update-databases. Brez telesa. Podatkovne zbirke z zaupanja vredno konfiguracijo in njihove nastavitve ter datoteke, ki jih modul izpusti:

{
  "folder": "C:\\ProgramData\\Wkl.Data.Gateway\\updates",
  "databases": [ {
    "id": "demo-prod", "gatewayAlias": "demo", "product": "Demo", "dialect": "sqlserver",
    "connection": { "string": "Server=sql01;Database=Demo;User ID=wkl_update;Encrypt=True",
                    "secret": "file:C:\\ProgramData\\Wkl.Data.Gateway\\secrets\\demo-update.txt" },
    "keys": [ "9c0f6d1e…" ],
    "inbox": "D:\\Updates\\Demo", "archive": "D:\\Updates\\Demo-Archiv",
    "backup": { "mode": "native", "target": "D:\\Sicherung" }, "starterSource": null,
    "settings": { "expand": "automatic", "contract": "confirm", "noticeMinutes": 60, "sessionWindowMinutes": 15 }
  } ],
  "problems": [ { "file": "alt.json", "code": 9, "message": "…" } ]
}

update-status. Telo { "database": "demo-prod" }. Odgovor je objekt stanja posodobitev podatkovnih zbirk (oblika 2), enak kot pri wkl-db status --json:

{
  "format": 2, "id": "demo-prod", "product": "Demo", "schema": 13,
  "packages": [ { "id": 41, "file": "Demo-schema-14.zip", "schema": 14, "kind": "contract",
                  "status": "announced", "reason": null, "message": null, "deadlineUtc": "2026-11-02T18:00:00Z" } ],
  "sessions": [ { "product": "Demo", "version": "2.3.1", "path": "gateway", "host": "10.1.2.17", "user": "FIRMA\\mustermann", "lastSeenUtc": "2026-11-02T16:40:12Z" } ],
  "drift": []
}

packages vsebuje pakete, ki niso nameščeni (done) ali opuščeni (dismissed): waiting (čaka na potrditev), announced (napoved teče, deadlineUtc je rok), running, failed, refused. reason je koda, ki pojasni stanje (glejte spodaj). sessions navede seje starejših aplikacij, ki zadržijo napovedani paket, in seje brez navedbe izdelka in različice, ki ga ne zadržijo; seje, ki potekajo prek storitve, storitev prepozna po glavi `X-Wkl-Application`. drift navede objekte, ki so bili od zadnjega paketa spremenjeni zunaj paketa, vsak vnos z object (ime s shemo), type (vrsta objekta, na primer table ali view) in change (changed, missing; dateChanged je pri šifriranem modulu samo namig in ne zadrži nobenega paketa).

update-history. Telo { "database": "demo-prod", "skip": 0, "take": 20 } (take od 1 do 100, privzeto 20). Zaključeni paketi (done, failed, refused, dismissed), najnovejši najprej, z id, file, schema, kind, status, reason, message, receivedUtc, confirmedBy, confirmedUtc, sha256 in steps: za vsak korak phase (predeploy, pre, model, post, postdeploy, baseline), version, path, sha256, appliedUtc, appliedBy, durationMs, result (ok, failed, rolledback) in message.

Odločitve. Telo { "database": "demo-prod", "package": 41 }; package je številka (id) iz stanja ali zgodovine.

upload-update. POST /admin/v1/upload-update?database=demo-prod&file=Demo-schema-14.zip, telo je datoteka ZIP, največ 64 MiB. Storitev jo postavi v vhodno mapo in jo takoj sprejme, kot datoteko, odloženo tja. Ime datoteke je samo ime brez poti.

Odgovor na odločitev ali nalaganje. message opiše, kaj se je zgodilo; package navede, kaj se je zgodilo s paketom, če se je izvedel ali bil napovedan (sicer null):

{ "message": "Angekündigt bis 2026-11-02 18:00:00Z.",
  "package": { "file": "Demo-schema-14.zip", "exitCode": 0, "outcome": "announced", "message": "Angekündigt bis 2026-11-02 18:00:00Z." } }

outcome je done (nameščen, datoteka je v arhivu in v done), announced, waiting (še čaka, na primer na potrditev ali na seje) ali failed (zavrnjen ali neuspel, datoteka je v failed). exitCode in reason uporabljata iste kode:

Skupnega klica ni: niti OData $batch niti ukaza za več oseb ali ključev. Vsaka oseba, vsaka dodelitev, vsak ključ je lastna zahteva.

Primer izračuna: 847 oseb z ustvarjanjem, dodelitvijo pravila in ključem je dobrih 2.500 zahtev, s privzeto vrednostjo torej najmanj devet minut. Če potrebujete več, za čas nastavitve zvišajte PerCaller.

Temu delu se pogosto lahko izognete. Osebe potrebujete le za tiste, ki dobijo osebne ključe, 2FA ali lastno privzeto identiteto. Pravice in pravila prijave je mogoče dodeliti skupini Windows kot celoti (WindowsAccounts, IdentityAssignments, značilnost windowsGroups pravil prijave), ne da bi njene člane vpisali posamično. 2FA pa ima vedno posamezna oseba: če pravilo zahteva 2FA za skupino, je vsak član brez vnosa osebe zavrnjen z 403 (glejte Prijava).

Prehod ne vrača seznamov članov. Imenika Active Directory nikoli ne poizveduje: katere skupine ima klicatelj, razbere ob prijavi iz njegove prijave Windows, imena pa ob shranjevanju razreši le v SID. Če želite vse člane skupine ustvariti kot osebe, jih preberite sami, na delovni postaji ali v skriptu (na primer Get-ADGroupMember oz. net group /domain), in nato za vsakega člana ustvarite osebo z WindowsAccount. Poznejših sprememb članstva prehod pri tem ne prevzame samodejno; pravice, podeljene prek same skupine, pa članstvu sledijo brez dodatnega vzdrževanja.

• Skrbniška shramba in glavni ključ
• Lastnosti povezave ponudnika
• „Priročnik za skrbnike aplikacije WKL Database Gateway Manager“