WklGatewayClient – razred VBA za podatkovni prehod

WklGatewayClient omogoča, da ukaze vmesnika za upravljanje podatkovnega prehoda (Wkl.Data.Gateway) kličete iz VBA: izdajo ključev, nastavitev 2FA (dvostopenjsko preverjanje identitete), preverjanje povezave in druge. Hkrati je predloga za vsako aplikacijo VBA, ki s prehodom komunicira prek HTTP.

Sezname (vire podatkov, pravila, osebe, ključe) aplikacija Access bere in ureja kot povezane tabele prek gonilnika ODBC prehoda. Kar vrne ključ ali drugo zaupno vrednost ali vpliva na več kot eno vrstico, je ukaz, in za ukaze je namenjen ta razred. Množice entitet in ukaze opisuje HTTP: skrbništvo (dokumentacija podatkovnega prehoda).

Microsoft Access iz Microsoft 365 v 32- in 64-bitni različici, v datoteki ACCDB, v datoteki ACCDE in v okolju Access Runtime. Aplikacija za upravljanje svoje ukaze kliče prek tega razreda.

1. V urejevalniku VBA izberite File > Import File in uvozite WklGatewayClient.cls in StringBuilder.cls (modula razreda, v skladišču pod source/classes/); če želite primere, uvozite še WklGatewayClientExamples.bas (pod client/). Če projekt modul razreda StringBuilder že ima, te datoteke ne uvozite.
2. Izberite Tools > References in označite „WKL Office JSON 1.1“ (do izdaje 1.0.3 „WKL Access JSON 1.0“).
3. Prevedite projekt (Debug > Compile).

Meniji so navedeni tako, kot jih prikazuje urejevalnik VBA v slovenskem Officeu, torej v angleščini; v nemškem Officeu se imenujejo Datei > Datei importieren, Extras > Verweise in Debuggen > Kompilieren.

Datoteki sta v obliki, ki jo urejevalnik VBA izvaža in uvaža. LoadFromText v Accessu za modul razreda pričakuje drugačno obliko (brez VERSION 1.0 CLASS … END in brez VB_Name); če prejme izvozno obliko, namesto modula razreda ustvari standardni modul. Kako eno obliko pretvorite v drugo, prikazuje client\tests\Run-AccessTests.ps1.

Za celotno sejo aplikacije uporabljajte en sam primerek razreda, ker ta hrani sejo 2FA.

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://podatki.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("Ana Novak", Label:="Prenosnik", Delivery:="link")
    Debug.Print answer.GetString("$.link")
    GoTo FinalHandler
 
ErrorHandler:
    MsgBox Err.Description, vbExclamation       ' Error numbers: see section "Napake"
    Resume FinalHandler
 
FinalHandler:
    Set answer = Nothing
End Sub

Komentarji v kodi so, kot je pri kodi običajno, v angleščini: ključ se prebere iz upravitelja poverilnic Windows, številke napak pa so navedene v razdelku Napake.

WklGatewayClientExamples.bas vsebuje vsak ukaz po enkrat, z obravnavo napak po številki.

Vsako prijavo (osebni ključ, ključ storitve, geslo in račun Windows) razred pošlje samo prek https ali lokalnemu računalniku; naslov http drugega računalnika zavrne z gwErrConfiguration, še preden kar koli pošlje. StoreKey ključ shrani pod istim ciljem, ki ga gonilnik ODBC uporablja za povezavo za upravljanje na isti naslov (Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@<BaseUrl>/admin/v1/odata/), zato en shranjeni ključ služi tako povezanim tabelam kot razredu. V datoteki podatkovne zbirke ključ ni nikoli shranjen.

Če prehod zahteva 2FA (odgovor 401 z glavo Wkl-Totp), razred pridobi kodo, jo zamenja za sejo in zahtevo ponovi. Kodo pridobi iz teh virov, v tem vrstnem redu:

1. iz lastnosti TotpCode (uporabi se enkrat), za kodo VBA, ki kodo za prijavo pridobi sama;
2. iz dogodka CodeRequired(Message, Code, Cancel) primerka, deklariranega z WithEvents;
3. iz okna InputBox (deluje tudi v okolju Access Runtime), ki ga izklopite z AskWithInputBox = False.

Če je koda napačna, razred s sporočilom prehoda vpraša znova, največ trikrat. OpenSession sejo izrecno odpre, ForgetSession jo zavrže. Gonilnik ODBC ima svojo sejo. Da ena koda zadošča za oba, aplikacija gonilniku preda SessionToken s ključno besedo SESSION= v povezavi, ki jo odpre sama (tako dela aplikacija za upravljanje). Brez te predaje gonilnik in razred kodo zahtevata vsak posebej.

Če se povezava prekine brez odgovora, razred zahtevo ponovi po 1 sekundi in nato še po 3 sekundah. Vsaka zahteva za pisanje nosi glavo Idempotency-Key, prehod pa na ponovitev odgovori z že pripravljenim odgovorom, namesto da bi pisal drugič. Ključ si prehod zapomni za 10 minut in samo v pomnilniku: če se med prekinitvijo in ponovitvijo znova zažene, se zahteva lahko izvede dvakrat (vedenje prehoda, kot ga opisuje HTTP: skrbništvo, razdelek „Veliko dejanj naenkrat“ (dokumentacija podatkovnega prehoda)). Zahteva, pri kateri poteče časovna omejitev (TimeoutSeconds, privzeto 60), se ne ponovi: prehod jo morda še izvede, razred pa tega ne more vedeti. V tem primeru podatke preberite znova in preverite, ali je bila sprememba uveljavljena.

• Ključe, gesla in prijavo Windows pošilja samo prek HTTPS ali lokalnemu računalniku; sicer zahtevo zavrne z napako gwErrConfiguration. WinHTTP potrdilo strežnika preveri v shrambi potrdil Windows; pri neveljavnem potrdilu zahteva ne uspe. Razred tega preverjanja nikoli ne izklopi.
• Key in Password hrani samo v pomnilniku svojega primerka. Ključ se shrani samo, če pokličete StoreKey, in še to samo v uporabnikovem upravitelju poverilnic Windows.
• Ključ storitve (gwServiceKey) se nikoli ne shrani v kodo ali podatkovno zbirko. Razred ga med izvajanjem prebere iz spremenljivke okolja, ki jo navaja KeyVariable. Kdor lahko bere to spremenljivko (vsak proces, ki teče pod tem uporabnikom), ima ključ.

Vsaka napaka se sproži s stalno številko (WklGatewayError) in opisom v nemščini, ki se konča s sporočilom prehoda, če ga ta vrne.

• Gonilnik in razred imata ločeni seji 2FA, dokler aplikacija seje ne preda s SESSION=.
• Vsak odgovor se v okviru časovne omejitve prebere v celoti. Za velike količine podatkov uporabite povezane tabele (prek gonilnika ODBC), ne tega razreda.