WklGatewayClient – VBA-Klasse für den Datendienst

WklGatewayClient ruft die Befehle der Verwaltungsschnittstelle des Datendienstes (Wkl.Data.Gateway) aus VBA auf: Schlüssel ausstellen, zweiten Faktor einrichten, Verbindung prüfen und weitere. Sie ist zugleich die Vorlage für jede VBA-Anwendung, die mit dem Dienst über HTTP spricht.

Listen – Datenquellen, Regeln, Personen, Schlüssel – liest und bearbeitet eine Access-Anwendung als verknüpfte Tabellen über den ODBC-Treiber des Dienstes. Was ein Geheimnis zurückgibt oder über eine Zeile hinaus wirkt, ist ein Befehl; dafür ist diese Klasse da. Die Mengen und Befehle selbst beschreibt die HTTP: Verwaltung (Referenz) (Dokumentation des Datendienstes).

Microsoft Access aus Microsoft 365 in 32 und 64 Bit, in einer ACCDB, einer ACCDE und in der Access-Runtime. Die Verwaltungsanwendung ruft ihre Befehle über diese Klasse auf.

1. Im VBA-Editor Datei → Datei importieren: die Klassenmodule WklGatewayClient.cls und StringBuilder.cls, bei Bedarf die Beispiele WklGatewayClientExamples.bas. Hat das Projekt schon ein Klassenmodul StringBuilder, entfällt dessen Import. Die Dateien liegen im Ordner vba-class der Lieferung: in der Freigabe bzw. im ZIP neben dem Starter, nach der Installation im Programmordner WKL\GatewayManager.
2. Extras → Verweise: „WKL Office JSON 1.1“ ankreuzen (bis Release 1.0.3 „WKL Access JSON 1.0“).
3. Kompilieren (Debuggen → Kompilieren).

Die Dateien liegen im Format, das der VBA-Editor exportiert und importiert. LoadFromText von Access erwartet für ein Klassenmodul ein anderes Format (ohne VERSION 1.0 CLASS … END und ohne VB_Name); mit dem Exportformat legt es ein Standardmodul an. Für LoadFromText entfernen Sie deshalb den Block von VERSION 1.0 CLASS bis zur ersten Zeile END und die Zeile Attribute VB_Name = …; die Datei beginnt dann mit den Zeilen Attribute VB_GlobalNameSpace ….

Eine Instanz für die ganze Sitzung der Anwendung: Sie hält die Sitzung des zweiten Faktors.

Private m_Client As WklGatewayClient
 
Public Function Gateway() As WklGatewayClient
    If m_Client Is Nothing Then
        Set m_Client = New WklGatewayClient
        m_Client.BaseUrl = "https://daten.example.com"
        m_Client.SignIn = gwPersonalKey          ' Key from Windows Credential Manager
    End If
    Set Gateway = m_Client
End Function
 
Sub Example()
    Dim answer As JDoc
    On Error GoTo ErrorHandler
 
    Set answer = Gateway().IssueKey("Erika Muster", Label:="Laptop", Delivery:="link")
    Debug.Print answer.GetString("$.link")
    GoTo FinalHandler
 
ErrorHandler:
    MsgBox Err.Description, vbExclamation       ' Error numbers: see section "Fehler"
    Resume FinalHandler
 
FinalHandler:
    Set answer = Nothing
End Sub

WklGatewayClientExamples.bas enthält jeden Befehl einmal, mit Fehlerbehandlung nach Nummer.

Jede Anmeldung – persönlicher Schlüssel, Dienstschlüssel, Kennwort und Windows-Konto – geht nur über https oder an den eigenen Rechner; eine http-Adresse eines anderen Rechners lehnt die Klasse vor dem Senden mit gwErrConfiguration ab. Den Schlüssel legt StoreKey unter demselben Ziel ab, das der ODBC-Treiber für eine Verbindung zur Verwaltung derselben Adresse verwendet (Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@<BaseUrl>/admin/v1/odata/): Ein gespeicherter Schlüssel dient den verknüpften Tabellen und der Klasse. In der Datenbankdatei steht er nie.

Verlangt der Dienst einen zweiten Faktor (Antwort 401 mit Wkl-Totp), erfragt die Klasse den Code, tauscht ihn gegen eine Sitzung und wiederholt die Anfrage. Woher der Code kommt, in dieser Reihenfolge:

1. Eigenschaft TotpCode (einmal verwendet) – für Code, der selbst fragt.
2. Ereignis CodeRequired(Message, Code, Cancel) einer Instanz mit WithEvents.
3. InputBox (läuft auch in der Runtime); abschaltbar mit AskWithInputBox = False.

Ein falscher Code wird mit der Meldung des Dienstes neu erfragt, höchstens dreimal. OpenSession eröffnet die Sitzung ausdrücklich, ForgetSession vergisst sie. Der ODBC-Treiber hält eine eigene Sitzung; damit ein Code für beide genügt, übergibt die Anwendung SessionToken dem Treiber mit dem Schlüsselwort SESSION= einer Verbindung, die sie selbst öffnet (so macht es die Verwaltungsanwendung). Ohne Übergabe fragen Treiber und Klasse je einmal.

Bricht die Verbindung ohne Antwort ab, wiederholt die Klasse die Anfrage nach 1 und 3 Sekunden. Jede Schreibanfrage trägt einen Idempotency-Key; der Dienst beantwortet eine Wiederholung aus seinem Gedächtnis, statt ein zweites Mal zu schreiben. Dieses Gedächtnis hält den Schlüssel 10 Minuten und nur im Arbeitsspeicher: Startet der Dienst zwischen Abbruch und Wiederholung neu, kann eine Anfrage doppelt ankommen (Vorgabe des Dienstes laut HTTP: Verwaltung (Referenz), Abschnitt „Viele Vorgänge auf einmal“ (Dokumentation des Datendienstes)). Eine abgelaufene Zeitgrenze (TimeoutSeconds, Vorgabe 60) wird nicht wiederholt: Der Dienst kann die Anfrage noch ausführen, die Klasse weiß es nicht. Lesen Sie in diesem Fall nach, ob die Änderung angekommen ist.

• Schlüssel, Kennwort und Windows-Anmeldung sendet sie nur über HTTPS oder an den eigenen Rechner; sonst lehnt sie mit gwErrConfiguration ab. Das Serverzertifikat prüft WinHTTP mit dem Zertifikatsspeicher von Windows; ein ungültiges Zertifikat lässt die Anfrage scheitern, die Klasse schaltet die Prüfung nicht ab.
• Key und Password hält sie nur im Arbeitsspeicher ihrer Instanz; gespeichert wird ein Schlüssel nur mit StoreKey in der Windows-Anmeldeinformationsverwaltung des Benutzers.
• Ein Dienstschlüssel (gwServiceKey) wird nie im Code oder in der Datenbank abgelegt, sondern zur Laufzeit aus der Umgebungsvariablen KeyVariable gelesen. Wer diese Variable lesen kann (jeder Prozess des Benutzers), hat den Schlüssel.

Jeder Fehler wird mit fester Nummer (WklGatewayError) und deutschem Text ausgelöst; der Text endet mit der Meldung des Dienstes, wo es eine gibt.

• Treiber und Klasse halten getrennte Sitzungen des zweiten Faktors, solange die Anwendung die Sitzung nicht mit SESSION= übergibt.
• Antworten bis zur Zeitgrenze werden ganz gelesen; für große Datenmengen sind die verknüpften Tabellen (ODBC-Treiber) der Weg, nicht diese Klasse.