HTTP: Verwaltung (Referenz)

Die Verwaltungsschnittstelle unter /admin/v1/ bietet den Verwaltungsspeicher als OData-Mengen und Befehle an; die Verwaltungsanwendung für Access und die VBA-Klasse DbGwClient bauen auf ihr auf.

Mit einem Verwaltungsspeicher bietet der Dienst dessen Tabellen unter /admin/v1/ an: als OData-Mengen, die ein Verwaltungsprogramm wie Tabellen verknüpft – Access über den ODBC-Treiber dieses Dienstes, mit den Formularen, die es für Tabellen ohnehin hat –, und als Befehle für das, was keine Änderung einer Zeile ist.

Warum zwei Formen. Was eine Liste ist, ist eine Menge: Ein Verwaltungsprogramm braucht dafür keinen eigenen Code. Was ein Geheimnis zurückgibt oder über die Zeile hinaus wirkt, ist ein Befehl: Eine Menge, die Access nach dem Anlegen neu liest, müsste den eben ausgestellten Schlüssel entweder wieder herausgeben oder verlieren.

Fertige Clients. Die „WKL Database Gateway Manager und VBA-Klasse – Überblick“ (Dokumentation der Verwaltungsanwendung) bedient alle Mengen und Befehle (Anmeldung mit Schlüssel oder Windows-Konto und zweitem Faktor); die „DbGwClient – VBA-Klasse für den Datendienst“ (Dokumentation der Verwaltungsanwendung) ruft die Befehle aus eigenen VBA-Anwendungen.

Mengen. Sie folgen den Tabellen des Speichers eins zu eins; Listen einer Regel oder eines Schlüssels sind Zeilen einer Untermenge mit dem Schlüssel der übergeordneten Zeile.

Felder zur Anzeige. Status ist ein Text für die Anzeige, StatusKind eine von fünf Arten (ok, warn, bad, info, neutral), nach der ein Verwaltungsprogramm das Etikett einfärbt – der Text steht immer dabei, die Farbe nie allein. Can…-Felder sagen, ob ein Zeilenbefehl gerade möglich ist. Der Dienst berechnet sie beim Lesen nach der Uhr des Speichers; sie sind schreibgeschützt (Schreiben 400) und gehören nicht zur Zeilenversion – ein Schlüssel ändert sich nicht dadurch, dass ein Tag vergeht. Geliefert statt in Access berechnet, weil ein Ausdruck wie IIf(…) in einer Access-Abfrage nicht über den ODBC-Treiber übersetzt wird und ein Datengitter im Server-Modus dann auf das langsame Lesen über Access zurückfiele.

Jede Menge hat die Eigenschaft Version (acht Bytes einer SHA-256 über die gespeicherten Werte der Zeile, versiegelte eingeschlossen) als Zeilenversion. Wer eine Zeile ändert, die ein anderer seit dem Lesen geändert hat, erhält 412 – in Access die gewohnte Meldung des Schreibkonflikts. Nummern sind int (Edm.Int32), nicht bigint: Access zeigt bigint ohne seine Option für große Zahlen als Text und lehnt dann eine Bedingung wie Id = 3 ab. Text vergleicht der Filter ohne Unterschied der Groß- und Kleinschreibung, wie SQL Server und wie der Speicher Namen vergleicht.

Die Verwaltung liest Zeilen und zählt sie; sie gruppiert nicht. $apply weist sie mit 400 ab, und ihr Schemadokument kündigt keine Gruppierung an (Aggregation.ApplySupported fehlt). Der ODBC-Treiber entscheidet nach dieser Ankündigung, was er an die Verwaltung schickt (Übersetzung im Einzelnen: „Unterstütztes SQL (Referenz)“ in der Dokumentation des ODBC-Treibers):

Zählen Sie mit DCount("*", …), nicht mit DCount("Spalte", …): Nur COUNT(*) wird zur Zählanfrage, mit oder ohne Bedingung.

Den höchsten Wert einer Spalte liefert die Verwaltung als erste Zeile einer absteigend sortierten Abfrage. Über HTTP, etwa mit dem eigenen HTTP-Zugriff eines Verwaltungsprogramms: GET /admin/v1/odata/SignInFindings?$select=Id&$orderby=Id desc&$top=1. Bei SignInFindings ist das selten nötig: Wer nur Neues zählen will, merkt sich die höchste gelesene Id und fragt SignInFindings/$count?$filter=Id gt 4711 (siehe Befunde der Anmelderegeln).

Jede Änderung wird vor dem Übernehmen geprüft. Eine Änderung ist eine Transaktion: Version vergleichen, schreiben, ins Änderungsprotokoll eintragen und den gesamten Inhalt danach so prüfen, wie ein Neuladen ihn prüft – einschließlich der Regeln, die eine Person nennt. Besteht er nicht, wird alles zurückgenommen, und die Antwort 422 nennt jeden Fehler. Ohne diese Prüfung stünde eine falsch geschriebene Regel im Speicher, jedes Neuladen würde sie ablehnen, und der Dienst bliebe unbemerkt auf der alten Version, obwohl die Schnittstelle Erfolg gemeldet hätte. Eine übernommene Änderung gilt sofort (der Dienst lädt neu, ohne auf PollSeconds zu warten). Eine Einschränkung des Speichers selbst (unbekannter Item, doppelter Schlüssel, Untereintrag ohne übergeordnete Zeile) beantwortet der Dienst ebenfalls mit 422 und der Meldung von SQLite.

Änderungsprotokoll. In derselben Transaktion wie die Änderung: Zeit, Aufrufer (Person (Kennung), Dienstname, Windows-Konto oder Einrichtung), Vorgang (insert, update, delete, command), Menge oder Befehl, Schlüssel, Werte vorher und nachher als JSON. Eine Verbindungszeichenfolge und Verbindungseigenschaften erscheinen nur als „neu gesetzt“, ein Schlüssel nie. Eine zurückgenommene Änderung hinterlässt keinen Eintrag; eine übernommene hat immer einen. Untereinträge, die mit ihrer übergeordneten Zeile gelöscht werden, stehen nicht einzeln darin.

Recht. Eine Regel muss die Ressource admin wörtlich nennen; * genügt nicht, wie beim Recht sql. Die Databases der Regel begrenzen die Verwaltung nicht – sie gehört zu keiner Datenquelle. Eine Regel für die Verwaltung:

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

Mit "ReadOnly": true liest dieselbe Regel die Verwaltung und prüft Verbindungen, ändert aber nichts (etwa für eine Revision):

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

Anmelden lässt sich an der Verwaltung mit persönlichem Schlüssel und Windows-Konto, mit einem Dienstschlüssel nur, wenn Gateway:Store:RequireAdminTotp = false ist und keine Anmelderegel für die Verwaltung einen zweiten Faktor verlangt – ein neuer Speicher enthält eine solche Regel (sonst 403 „… gehoert zu keiner Person“, weil ein Dienstschlüssel keinen zweiten Faktor haben kann), nicht mit einer SQL-Anmeldung: Deren Kennwort prüft SQL Server an einer Datenquelle, und die Verwaltung gehört zu keiner. Ein persönlicher Schlüssel, der auf Datenquellen beschränkt ist, erreicht die Verwaltung nie; ein nur lesender Schlüssel liest sie höchstens. Jede Adresse der Schnittstelle antwortet nur über eine geschützte Verbindung: HTTPS, ein vertrauter Proxy mit X-Forwarded-Proto: https oder eine Anfrage vom eigenen Rechner. Sonst 403, auch für den Einmal-Link.

Erster Administrator. Die Verwaltung erreicht nur, wen eine Regel mit admin nennt. Die erste solche Person legt der Befehl init-admin am Server an, nicht eine Anfrage über das Netz, siehe Erster Administrator und Rettung.

Einmal-Link. issue-key mit "delivery": "link" gibt statt des Schlüssels eine Adresse zurück, gültig für Gateway:Store:PickupMinutes (Vorgabe 15 Minuten, siehe Konfiguration). Die Seite dahinter zeigt beim Öffnen nur eine Schaltfläche; erst deren POST zeigt den Schlüssel, einmal. So holt ein Mailprogramm oder Chat, der Links zur Vorschau öffnet, den Schlüssel nicht vorher ab. Der wartende Schlüssel liegt nur im Speicher des Prozesses, nie auf der Platte; ein Neustart macht offene Links ungültig. Die Abholung steht im Änderungsprotokoll (Einmal-Link, mit Herkunft).

<a id=„einmal-link-per-mail“></a>Einmal-Link per Mail. issue-key und enroll-totp mit "delivery": "mail" geben eine Adresse für eine Einladungsmail zurück (person, delivery, link, linkExpiresAt), gültig mail_link_hours bzw. MailLinkHours (Vorgabe 72 Stunden). Anders als ein gewöhnlicher Einmal-Link:

• Kein Geheimnis wartet. Der Speicher hält den Auftrag und die SHA-256-Prüfsumme des Links, keinen Schlüssel. Schlüssel bzw. zweiter Faktor entstehen erst beim Abholen; bis dahin bleibt ein vorhandener Faktor der Person unverändert. Eine Kopie der Speicherdatei öffnet daher nichts.
• Übersteht einen Neustart des Dienstes.
• Genau einmal. Ein zweites Öffnen zeigt „bereits abgeholt am … um …“ (410) mit der Bitte, das der Verwaltung zu melden, falls der Empfänger es nicht selbst war; ein abgelaufener oder unbekannter Link 404.
• Antwort ohne Schlüsselkennung: Den Schlüssel gibt es erst nach dem Abholen; er erscheint dann in PersonalKeys. Ein expiresAt vor dem Ende des Links lehnt der Dienst mit 400 ab.
• Protokoll: Ausstellen als Befehl mit delivery: mail, Abholen als issue-key bzw. enroll-totp mit dem Akteur Einmal-Link von <Aussteller> und der Herkunft.
• Lässt sich der Auftrag beim Abholen nicht mehr erfüllen (Person entfernt), zeigt die Seite das mit 409; der Link bleibt dann unverbraucht.

{ "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" }

Für alle Mengen und Befehle der Verwaltung:

test-connection. Rumpf { "dataSource": "fachdaten" }. Die Antwort nennt dataSource, reachable, elapsedMilliseconds, productVersion, database und login; ist die Datenquelle nicht erreichbar, dazu message (die Meldung des Servers in seiner Sprache), number und failure. Der Test öffnet die Verbindung einmal, ohne Verbindungspool, und meldet die Antwort des Servers; eine Wiederholung des Datenbanktreibers gibt es dabei nicht. Nur auf 233 („kein Prozess am anderen Ende der Pipe“) öffnet er sofort ein zweites Mal: Ein SQL Server auf demselben Rechner meldet eine abgelehnte Anmeldung über Shared Memory oder Named Pipes manchmal so statt mit 18456. Antwortet der Server wieder mit 233, ist er tatsächlich nicht erreichbar:

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

number ist die Nummer der Datenbank (bei SQL Server die Fehlernummer); leer, wenn es keine gibt. failure ordnet den Fehler unabhängig von der Sprache des Servers ein; ein Programm erklärt danach die Ursache und schlägt die Abhilfe vor:

Ein Provider, der für eine ältere Version des Provider-Vertrags gebaut ist, liefert number und failure nicht; sie bleiben dann leer.

service-account. Ohne Rumpf. Das Konto, unter dem eine Datenquelle mit Windows-Anmeldung (Integrated Security) sich an der Datenbank anmeldet – der Name, für den eine Datenbankverwaltung die Anmeldung anlegt:

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

Was SQL Server für dieses Konto braucht, steht unter Installation – Hinweise.

Schlüssel auf Abruf. issue-key mit "onDemand": true stellt einen Schlüssel aus, der ruht, bis die Verwaltung ihn freischaltet. activate-key mit { "id": "k…", "hours": 4 } schaltet ihn frei; eine neue Freischaltung ersetzt die laufende. Abgelehnt (400, die Meldung nennt den Grund) wird ein Schlüssel, der nicht auf Abruf gilt, gesperrt oder abgelaufen ist, eine Dauer über max_activation_hours und eine Freischaltung über das Ablaufdatum des Schlüssels hinaus. deactivate-key mit { "id": "k…" } beendet sie sofort. Beides steht mit Akteur im Änderungsprotokoll; die Antwort nennt activeUntil.

Anmelderegel in einem Schritt. Eine Regel gilt, sobald sie gespeichert ist. Über die Mengen entstehen zuerst die Regel und danach ihre Merkmale – eine Ablehnung gilt dazwischen für alle, auch für den, der sie speichert. save-sign-in-rule schreibt Regel und Merkmale in einer Änderung:

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

Weitere Listen: from, persons, windowsGroups, exceptWindowsGroups, countries, exceptCountries, operators, exceptOperators, clients, exceptClients, hours, exceptHours (Bedeutung unter Anmelderichtlinie). Netzbetreiber speichert der Dienst als AS mit Nummer, Zeitfenster in ausgeschriebener Form (Mon-Fri wird Mon,Tue,Wed,Thu,Fri 00:00-24:00). mode ist Enforce (Vorgabe) oder Report für eine Regel in Probe. Befristete Ausnahmen stehen in exceptions, je mit persons, windowsGroups, countries, from, operators, clients, hours, until (UTC) und label:

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

Mit "id" ersetzt der Befehl die Regel samt allen Merkmalen und Ausnahmen; ohne legt er eine neue an. Antwort { "id" }. Eine unbekannte Person oder Regel beantwortet der Dienst mit 400, einen danach ungültigen Inhalt mit 422; in beiden Fällen bleibt nichts gespeichert.

Anmeldung erklären. explain-sign-in rechnet mit derselben Richtlinie wie eine echte Anmeldung, was für eine Person gilt – für jede Anmeldeart der Person (Windows-Konto, SQL-Anmeldung, jeder persönliche Schlüssel) und jede genannte Herkunft:

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

Eine Herkunft darf ihr Land mit country selbst nennen; so lässt sich „was gilt für Frank in Thailand?“ fragen, ohne eine Adresse von dort zu kennen. Ohne country liest der Dienst das Land wie bei einer echten Anmeldung aus der Geodatenbank. Ebenso nimmt eine Herkunft operator (Netzbetreiber, AS3320; ohne Angabe aus der Geodatenbank), client (Programmart; ohne Angabe unbekannt) und at (Zeitpunkt in UTC; ohne Angabe jetzt), etwa { "name": "Samstag mit Excel", "address": "203.0.113.7", "client": "Power Query", "at": "2026-10-24T10:00:00Z" }.

Die Antwort führt je Anmeldeart (ways) eine Zelle je Herkunft mit result – allowed, code (zweiter Faktor nötig), denied oder ein Zustand, der vor der Richtlinie greift: revoked, expired, rests (Schlüssel auf Abruf ruht), personDisabled, outsideKeyNetworks – und den zutreffenden Regeln (id, version, label, effect, method, scope); floor zeigt die Untergrenze der Verwaltung, country das Land, nach dem geurteilt wurde (leer, wenn es unbekannt ist oder keine Regel Länder nennt), operator, client und at die übrigen beurteilten Signale, tried die Regeln in Probe, die zuträfen (wie rules; sie gehen nicht in result ein), und spared die Regeln, von denen eine Ausnahme befreit (id, version, rule, effect, exception, until). id und version sind dieselben Werte, die ein Anmeldeereignis nennt (siehe Grundlage der Entscheidung); so lässt sich prüfen, ob eine Regel noch so steht wie bei einer früheren Anmeldung. Ein Windows-Konto wird ohne seine Gruppen beurteilt, denn die kennt nur eine echte Anmeldung; nennt eine Regel Gruppen, steht groupsUnknown dabei. 1 bis 16 Herkünfte je Aufruf.

Das Anmeldeprotokoll hält jede Anmeldeentscheidung mit Herkunft in der Protokolldatei neben dem Speicher fest (Einstellungen unter `Gateway:SignInLog`, Vorgehen in So prüfen Sie Anmeldemuster und Herkunft). Der Dienst schreibt die gesammelten Entscheidungen einmal in der Minute und wendet dabei die Anmelderegeln an; eine Anmeldung erscheint in den Mengen also bis zu einer Minute später. Alle Mengen sind nur lesbar. SignInFindings liest gespeicherte Befunde, die übrigen Mengen werden beim Lesen berechnet.

Werte. Method: apiKey, personalKey, windows, sqlLogin, none. Outcome: success, refused, challenge (Anfrage ohne Anmeldedaten oder Zwischenschritt einer Windows-Anmeldung; auch die Aufforderung zum zweiten Faktor), totpSuccess, totpFailure. NetClass: loopback, private (eigenes Netz, RFC 1918, eindeutig lokale IPv6-Adressen, Link-Local, 100.64.0.0/10), public, unknown. In SignInHours ist Country leer, wenn kein Land bekannt ist. Reason (bei refused): notSignedIn, unknownKey, revoked, expired, rests, personDisabled, outsideKeyNetworks, denied, deniedByCountry (jede ablehnende Regel nennt Länder), noPerson, enrolmentOpen, noFactor, secondFactorMissing, sessionExpired, limit, unprotected (Anmeldung, die nur über eine geschützte Verbindung angenommen wird, kam unverschlüsselt). Presented nennt einen angegebenen, unbekannten SQL-Anmeldenamen, nie einen Schlüssel. Client ist die Art des Programms aus der Kopfzeile User-Agent (Power Query, WinHTTP, PowerShell, Browser oder das erste Wort); leer ohne Kopfzeile.

Jedes Anmeldeereignis, das die Anmelderichtlinie beurteilt hat, nennt in Rules die Regeln, nach denen entschieden wurde, und in Signals die Signale, nach denen geurteilt wurde – beides als JSON-Text. Ein Ereignis ohne gültigen ersten Faktor (falscher Schlüssel, falsches Kennwort) erreicht die Richtlinie nicht; dort sind beide Felder leer.

Rules ist eine Liste; leer ([]), wenn keine Regel zutraf. Jeder Eintrag nennt:

Signals nennt, was über die Spalten des Ereignisses hinaus in die Entscheidung einging:

Verfahren, Person, Schlüssel und Herkunft stehen in den Spalten des Ereignisses (Method, Person, KeyId, Origin, NetClass, NetName); Client ist eine Behauptung des Programms und entscheidet nur, wenn eine Regel nach dem Programm fragt. Gleiche Ablehnungen einer Minute fasst das Protokoll nur zusammen, wenn dieselben Regeln in derselben Version entschieden haben. Gesucht wird mit contains, etwa $filter=contains(Rules,'"id":"7"') für alle Anmeldungen, an denen die Regel 7 beteiligt war.

Recht sign-in-events. Eine Regel muss die Ressource wörtlich nennen, zusätzlich zu admin; weder * noch admin allein gewähren sie. Adresse und Person je Anmeldung sind personenbezogene Daten; das Recht trennt, wer Zählungen und Muster sieht, von wer einzelne Personen verfolgen kann. Es gilt für SignInEvents, für die Personenfelder von SignInFindings und SignInAdvice und für `sign-in-profile`. Ohne das Recht sind diese Felder leer, bevor der Filter einer Anfrage greift; eine Bedingung auf sie trifft dann nichts.

Bei jedem Schreiben wendet der Dienst die Anmelderegeln auf die neuen Ereignisse an und speichert, was eine Regel erkennt, als Befund. Ein Befund wird einmal geschrieben und nie neu bewertet; er nennt die Regel mit ihren Schwellen (RuleVersion) und den Vergleichszeitraum (BaselineDays), unter denen er entstand. Dieselbe Lage – Regel, Herkunft oder Person, Stunde oder Tag – ergibt nur einen Befund.

Seit dem letzten Blick. Id steigt mit jedem Befund und wird nie wiederverwendet. Ein Programm merkt sich die höchste gelesene Id und fragt danach mit $filter=Id gt 4711 nur Neues ab. Mit einer Bedingung auf Id liest der Dienst die ältesten passenden Befunde zuerst; so liest ein Programm auch mehr als 20 000 neue Befunde vollständig in Schritten. Ohne eine solche Bedingung liefert er die neuesten.

Stufen. act verlangt Handeln: ein Angriffsmuster oder ein weitergegebener Schlüssel. ask ist eine Frage an die Person wert: Etwas ist für sie neu oder ungewöhnlich. Wohin der Dienst Befunde meldet, regelt `Gateway:SignInLog:Alerts`.

Die Regeln über Neues sprechen erst, wenn die Person in den 90 Tagen davor mindestens 5 erfolgreiche Anmeldungen hatte, unusualHour erst ab 20; vorher wäre alles neu. Tage und Stunden zählen in der Zeitzone von Gateway:SignInLog:TimeZone. Observed ist der beobachtete Wert (ein Land, eine Anzahl, eine Strecke), Usual sind die üblichen Werte der Person zum Vergleich. Der Text eines Befunds nennt nie eine Person.

sign-in-profile zeigt, was für eine Person bei der Anmeldung üblich ist – etwa, um einen Befund newCountry einzuordnen. Rumpf:

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

days zählt ab heute zurück, heute eingeschlossen, in der Zeitzone von Gateway:SignInLog:TimeZone; Vorgabe 90, erlaubt 1 bis 3 650. Die Antwort nennt person, days, from, until, total (erfolgreiche Anmeldungen) und activeDays sowie unter dimensions je Merkmal – country, network, operator, client, method, hour (Stunde 00 bis 23) – die Werte mit value, count, firstDay und lastDay, die häufigsten zuerst. Ein Ausschnitt:

{ "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" } ] } }

Es zählen nur erfolgreiche Anmeldungen. Das Profil stammt aus Tageswerten je Person, die in der Protokolldatei länger bleiben als die einzelnen Ereignisse. Es braucht das Recht sign-in-events (sonst 403) und gilt immer für genau eine Person; eine Liste über Personen gibt es nicht. Unbekannte Person: 404; days außerhalb des Bereichs: 400.

set-geoip-source. Rumpf:

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

source ist Pflicht: none (nur Dateien per upload-geoip), dbip-lite oder maxmind. updateDays 0 bis 90: nach so vielen Tagen lädt der Dienst von selbst neu (0 = nur auf Befehl); nach einem gescheiterten Versuch versucht er es nach sechs Stunden wieder. licenseKey wird mit dem Hauptschlüssel versiegelt gespeichert; fehlt er im Rumpf, bleibt der gespeicherte, "removeLicenseKey": true entfernt ihn. maxmind ohne Kontonummer oder Lizenzschlüssel: 422. Das Änderungsprotokoll nennt nur, ob ein Schlüssel gesetzt ist.

update-geoip. Ohne Rumpf. Lädt beide Dateien und nimmt sie in Gebrauch, ohne Neustart. Antwort files mit je kind, databaseType, buildDate, bytes, changed, attribution; eine Datei mit demselben Erstellungsdatum wie die vorhandene bleibt unverändert (changed: false). Abgelehnt mit 422 und Grund: keine Quelle gewählt, Quelle lehnt ab oder liefert nichts, Datei unbrauchbar. Läuft schon ein Laden: 422.

upload-geoip. Rumpf ist die Datei selbst (.mmdb, .mmdb.gz oder das .tar.gz von MaxMind), Content-Type: application/octet-stream. Abfrageoptionen: source=dbip-lite|maxmind bestimmt die Namensnennung, force=true übernimmt auch eine ältere oder gleich alte Datei. Die Art (City, Asn) erkennt der Dienst am Inhalt. Antwort wie ein Eintrag von update-geoip. Größer als GeoIp:MaxMegabytes: 429 (LIMIT_EXCEEDED) wie jeder zu große Rumpf; unbrauchbar oder älter als die vorhandene: 422.

Ausgehend ist nur das Laden der Dateien; eine Adresse eines Aufrufers verlässt den Server nie.

Das Lastprotokoll hält fest, was jede Form einer Anfrage kostet (Einstellungen unter `Gateway:LoadLog`, Vorgehen in So finden Sie heraus, was den Dienst und die Datenbank belastet). Eine Form ist eine Anfrage ohne ihre Werte: Weg, Alias, Art, Objekt, verglichene Felder, Sortierung und Fenster, jeder Wert als ?. Anfragen, die sich nur in Werten unterscheiden, sind eine Form. Der Dienst schreibt die gesammelten Zahlen einmal in der Minute in die Protokolldatei; eine Anfrage erscheint also bis zu einer Minute später. Alle Mengen sind nur lesbar. LoadFindings liest gespeicherte Hinweise, die übrigen Mengen werden beim Lesen berechnet.

Werte. Path: odata (OData-Oberfläche), cf (eigene Routen unter /api/v1/cf/), checked (geprüfte Anweisung), passthrough (Anweisung mit dem Recht sql), admin (Verwaltung), other (zweiter Faktor, Selbstbedienung, Downloads). Kind: read, count, aggregate, call, insert, update, delete, statement, describe (Anweisung nur beschrieben), service (Anfrage ohne Daten: Metadaten, Abweisung, Verwaltung). Den Text einer Anweisung führt der Dienst ohne Literale und Kommentare; lange Wertelisten werden zu ?, … zusammengelegt. Übersprungene Zeilen ($skip) erscheinen in Text nur als Stufe, nie mit ihrer Zahl: skip=small (unter 1 000), skip=medium (unter 10 000), skip=large (ab 10 000).

Zeiten und Mengen. TotalMs ist die ganze Zeit der Anfrage im Dienst, DataMs der Teil ab dem Öffnen der Verbindung zur Datenquelle bis zur letzten gelesenen Zeile, einschließlich des Wechsels auf die Identität der Person. Das 95. Perzentil (P95Ms) ist die Obergrenze der Zeitstufe, in die es fällt (Stufen 5, 10, 25, 50, 100, 250, 500, 1 000, 2 500, 5 000, 10 000, 30 000 ms; darüber MaxMs). Bytes zählt die Antwort vor der Komprimierung. Errors zählt Antworten 5xx, Refused Antworten 4xx. Person ist der Name der Person, ohne Person die Kennung des Aufrufers wie im Audit. Summen von Zeit, Zeilen und Bytes sind Gleitkommazahlen, damit ein Programm wie Access, das ganze Zahlen mit 32 Bit liest, nicht überläuft.

Hinweise (LoadAdvice). Jeder Code ist ein Muster, das die Datenbank unabhängig von den Daten belastet:

Recht load-persons. Eine Regel muss die Ressource wörtlich nennen, zusätzlich zu admin; weder * noch admin allein gewähren sie. Die Last je Person zeigt, wer wann wie viel gearbeitet hat; das Recht trennt, wer die Last des Dienstes sieht, von wer Personen vergleichen kann.

export-load. Rumpf optional:

{ "days": 30 }

days 1 bis HourDays, Vorgabe 30. Die Antwort ist eine JSON-Datei wkl-load-JJJJMMTT-hhmmss.json im Format wkl-load-export/1 mit shapes, hours, advice und den Grenzen der Zeitstufen (histogramBounds). Sie enthält die Namen von Aliassen, Objekten und Spalten, aber keine Personen, Schlüssel, Adressen, Korrelationskennungen und keine Werte; die Tageszahlen je Person und die langsamen Einzelanfragen werden dafür gar nicht gelesen. Das Recht ist das Lesen der Verwaltung; der Abruf steht im Änderungsprotokoll.

Der Dienst kennzeichnet jede Anweisung, die er selbst erzeugt, mit der Kennung ihrer Form als Kommentar hinter dem ersten Schlüsselwort, etwa SELECT /* wkl:5b9b83f10953 */ TOP (1) … oder UPDATE /* wkl:8b7d7b280081 */ [dbo].[Probe] SET …. Dort bleibt er auch im Query Store erhalten, der einen Kommentar vor oder hinter einer Anweisung nicht speichert. Bei einem Prozeduraufruf steht die Kennung vor dem Aufruf; der Query Store führt dann die Anweisungen der Prozedur ohne Kennung. Mit dieser Kennung findet eine Datenbankverwaltung die Form im Plancache, im Query Store oder in Extended Events und kommt von dort zu LoadShapes. Geprüfte Anweisungen tragen die Kennung ebenso; eine Anweisung mit dem Recht sql läuft unverändert, ohne Kennung. Die Verbindungen nennen sich gegenüber SQL Server Wkl.Data.Gateway (program_name), sofern die Verbindungszeichenfolge der Datenquelle keinen eigenen Application Name setzt.

Das Update-Modul des Dienstes spielt signierte Datenbank-Updates (Pakete <Produkt>-schema-<Version>.zip) in die Datenbanken ein, für die der Ordner `Gateway:Updates` eine geschützte Konfiguration hat. Es sieht alle PollSeconds Sekunden nach: Pakete im Eingang, deren Kopie seit mindestens 5 Sekunden abgeschlossen ist, und angekündigte Pakete, deren Frist abgelaufen ist. Die Befehle zeigen den Stand und führen die Entscheidungen der Verwaltung aus.

Rechte. update-databases, update-status und update-history lesen (Regel mit admin, auch nur lesend). Jede Entscheidung braucht das Recht zum Ändern und steht im Änderungsprotokoll mit Datenbank, Paket und Ergebnis.

update-databases. Ohne Rumpf. Die Datenbanken mit vertrauenswürdiger Konfiguration und ihren Einstellungen, dazu die Dateien, die das Modul auslässt:

{
  "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. Rumpf { "database": "demo-prod" }. Antwort: das Statusobjekt der Datenbank-Updates (Format 2), dasselbe wie 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 enthält die Pakete, die nicht eingespielt (done) oder verworfen (dismissed) sind: waiting (wartet auf Bestätigung), announced (Ankündigung läuft, deadlineUtc ist die Frist), running, failed, refused. reason ist der Code, der den Status erklärt (siehe unten). sessions nennt Sitzungen älterer Anwendungen, die ein angekündigtes Paket aufhalten, und Sitzungen ohne Angabe von Produkt und Version, die nicht aufhalten; Sitzungen über den Dienst erkennt der Dienst am Kopf `X-Wkl-Application`. drift nennt Objekte, die seit dem letzten Paket außerhalb eines Pakets geändert wurden, je Eintrag mit object (Name mit Schema), type (Art des Objekts, etwa table oder view) und change (changed, missing; dateChanged ist bei einem verschlüsselten Modul nur ein Hinweis und hält kein Paket auf).

update-history. Rumpf { "database": "demo-prod", "skip": 0, "take": 20 } (take 1 bis 100, Vorgabe 20). Abgeschlossene Pakete (done, failed, refused, dismissed), neueste zuerst, mit id, file, schema, kind, status, reason, message, receivedUtc, confirmedBy, confirmedUtc, sha256 und steps: je Schritt phase (predeploy, pre, model, post, postdeploy, baseline), version, path, sha256, appliedUtc, appliedBy, durationMs, result (ok, failed, rolledback) und message.

Entscheidungen. Rumpf { "database": "demo-prod", "package": 41 }; package ist die Nummer (id) aus Status oder Verlauf.

upload-update. POST /admin/v1/upload-update?database=demo-prod&file=Demo-schema-14.zip, Rumpf = die ZIP-Datei, höchstens 64 MiB. Der Dienst legt sie in den Eingang und nimmt sie sofort an, wie eine dort abgelegte Datei. Der Dateiname ist ein reiner Name ohne Pfad.

Antwort einer Entscheidung oder eines Hochladens. message beschreibt, was geschah; package nennt, was aus dem Paket wurde, wenn es lief oder angekündigt wurde (sonst 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 ist done (eingespielt, Datei im Archiv und in done), announced, waiting (wartet weiter, etwa auf Bestätigung oder auf Sitzungen) oder failed (abgelehnt oder gescheitert, Datei in failed). exitCode und reason verwenden dieselben Codes:

Einen Sammelweg gibt es nicht: weder OData-$batch noch einen Befehl für mehrere Personen oder Schlüssel. Jede Person, jede Zuordnung, jeder Schlüssel ist eine eigene Anfrage.

Rechenbeispiel: 847 Personen mit je Anlegen, Regelzuordnung und Schlüssel sind gut 2 500 Anfragen, mit der Vorgabe also mindestens neun Minuten. Wer schneller sein muss, hebt PerCaller für die Dauer der Einrichtung an.

Der Aufwand lässt sich oft vermeiden. Personen braucht nur, wer persönliche Schlüssel, einen zweiten Faktor oder eine eigene Vorgabe-Identität bekommt. Rechte und Anmelderegeln lassen sich einer Windows-Gruppe als Ganzem zuordnen (WindowsAccounts, IdentityAssignments, Merkmal windowsGroups der Anmelderegeln), ohne ihre Mitglieder einzeln einzutragen. Ein zweiter Faktor gehört dagegen immer einer Person: Verlangt eine Regel ihn für eine Gruppe, wird jedes Mitglied ohne Personeneintrag mit 403 abgewiesen (siehe Anmeldung).

Der Dienst liefert keine Mitgliederlisten. Er fragt das Active Directory nie ab: Welche Gruppen ein Aufrufer hat, entnimmt er bei der Anmeldung dessen Windows-Anmeldung, und Namen löst er beim Speichern nur zur SID auf. Wer alle Mitglieder einer Gruppe als Personen anlegen will, liest sie selbst aus, am Arbeitsplatz oder in einem Skript (etwa Get-ADGroupMember bzw. net group /domain), und legt dann je Mitglied eine Person mit WindowsAccount an. Spätere Ein- und Austritte in der Gruppe übernimmt der Dienst dabei nicht von selbst; Rechte, die über die Gruppe selbst vergeben sind, folgen der Mitgliedschaft dagegen ohne Nachpflege.

• Verwaltungsspeicher und Hauptschlüssel
• Verbindungseigenschaften eines Providers (Referenz)
• „Administrator-Handbuch für WKL Database Gateway Manager“ (Dokumentation der Verwaltungsanwendung)