Niz povezave gonilnika (referenca)
Niz povezave – ali istoimenske vrednosti vira podatkov (DSN) – določa, na katero storitev OData se gonilnik obrne in kako se prijavi. Ta stran navaja vsako ključno besedo s privzeto vrednostjo in učinkom; potrebujete jo, ko povezavo ustvarite s kodo, distribuirate vir podatkov ali vzpostavite povezavo v .NET ali VBA.
Sintaksa
DRIVER={Wkl OData};URL=<koren-storitve>[;<ključna-beseda>=<vrednost>]…
DSN=<ime-vira-podatkov>[;<ključna-beseda>=<vrednost>]…
Velike in male črke ključnih besed niso pomembne. Vrednost, ki vsebuje podpičje, zapišite v zavite
oklepaje, kot pri vsakem gonilniku ODBC. Obliko niza in vloge DRIVER, DSN, UID in PWD določa specifikacija ODBC
(Microsoft:
SQLDriverConnect);
vse druge ključne besede so ključne besede tega gonilnika.
Obvezen je samo URL (ali vir podatkov, ki ga navaja).
Parametri
| Ključna beseda | Privzeto | Pomen |
|---|---|---|
DRIVER | – | registrirano ime gonilnika, {Wkl OData}. Obvezno, če ni naveden DSN |
DSN | – | vir podatkov, iz katerega gonilnik prebere druge vrednosti |
FILEDSN | – | datotečni vir podatkov; upravitelj gonilnikov ga prebere in posreduje njegove vrednosti |
DESCRIPTION | – | opis vira podatkov v pogovornem oknu za nastavitev; brez učinka na povezavo |
URL | – | korenski naslov storitve, pod katerim je $metadata, http ali https. Obvezno; če manjka, se povezava konča z napako 08001 |
DATABASE | vrednost vira podatkov, sicer koren storitve | loči povezave v Accessu; gonilnik ga dopolni sam, glejte Vrnjeni niz povezave. Pogovorno okno za nastavitev ga zapiše v vsak vir podatkov |
AUTH | – | postopek prijave: WINDOWS, BASIC ali KEY. Druga vrednost prepreči povezavo |
UID | – | ime prijave z geslom (HTTP Basic), na primer prijave SQL Server, ki jo preveri storitev |
PWD | prazno | geslo k UID; pri AUTH=KEY osebni ključ |
SAVEPWD | – | zapiše ga samo pogovorno okno za nastavitev: 1, če je bilo označeno „Kennwort speichern“ (Shrani geslo) oziroma „Schlüssel speichern“ (Shrani ključ). Sama vrednost se shrani v upravitelj poverilnic Windows, nikoli v vir podatkov |
APIKEY | – | ključ storitve kot navadno besedilo. Ni za povezave v Accessu, glejte opombe |
APIKEYENV | – | ime spremenljivke okolja, ki vsebuje ključ storitve. Če je prazna, se povezava konča z napako 28000 |
APIKEYHEADER | X-Api-Key | glava, v kateri se pošiljata ključ storitve in osebni ključ |
TOTP | – | koda 2FA za prvi izziv storitve, za aplikacije brez pogovornega okna. Velja enkrat in 30 sekund |
SESSION | – | seja 2FA, ki jo je aplikacija odprla sama. Samo prek https ali na lastni računalnik |
ROLE | – | identiteta podatkovne zbirke, pod katero storitev izvaja stavke, če jih storitev ponuja več. Največ 128 znakov; ni zaupen podatek |
PASSTHROUGH | navedba storitve | naslov za stavke, ki jih ni mogoče prevesti v OData; absoluten ali relativen glede na koren storitve. Če manjka, velja naslov, ki ga storitev navede v $metadata (Store.PassThrough) – vendar samo z isto shemo, računalnikom in vrati kot URL, da dokument metapodatkov prijave ne more preusmeriti drugam. OFF izklopi oboje |
TIMEOUT | 60 | sekunde na zahtevo, če aplikacija za stavek ne nastavi časovne omejitve; 0 pomeni brez omejitve. Negativno število ali besedilo: povezava se konča z napako 08001. Časovna omejitev aplikacije (SQL_ATTR_QUERY_TIMEOUT, v ADO.NET CommandTimeout) ima prednost; če aplikacija tam nastavi 0, ne velja nobena omejitev |
RETRY | ON | z OFF gonilnik prekinjeno povezavo takoj javi kot 08S01, namesto da bi zahtevo ponovil; za storitev, ki ne upošteva Idempotency-Key. Druga vrednost: 08001 |
MAXURLLENGTH | 2000 | najdaljši naslov bralne zahteve. Daljša zahteva se pošlje kot POST …/$query z možnostmi v telesu; z 0 se tako pošlje vsaka bralna zahteva. Ni število: povezava se konča z napako 08001 |
TRACEFILE | – | datoteka za sledenje gonilnika, glejte sledenje |
Spremenljivke okolja, ki jih gonilnik bere poleg tega:
| Spremenljivka | Učinek |
|---|---|
WKL_ODATA_ODBC_TRACE | datoteka za sledenje, če povezava ne navaja TRACEFILE |
WKL_ODBC_DIALOG_THEME | light ali dark: videz pogovornih oken neodvisno od načina aplikacij v sistemu Windows |
Vrnjeni niz povezave
SQLDriverConnect niz povezave vrne takšen, kakršen je prispel, s štirimi izjemami. Access pri povezovanju
ta vrnjeni niz shrani v povezano tabelo; niz, ki ga koda pozneje nastavi sama (TableDef.Connect z
RefreshLink), ostane takšen, kot je nastavljen.
TOTP in SESSION manjkata. Niz, ki ga Access shrani k povezani tabeli, ju ne vsebuje, sledenje
pa ne prikaže njunih vrednosti.
ROLE se dopolni, če je uporabnik v pogovornem oknu izbral identiteto.
Po pogovornem oknu za prijavo gonilnik vrne podatke, ki jih je uporabnik vnesel v pogovornem
oknu, na primer AUTH in UID. Izpusti APIKEY, razen če ga je aplikacija podala sama, geslo, če ga
je uporabnik shranil v upravitelj poverilnic, in vrednosti, ki so nespremenjene že shranjene v viru
podatkov.
DATABASE se dopolni. Če niz ne navaja DATABASE, ga gonilnik doda: vrednost, ki jo shrani vir
podatkov, sicer koren storitve (DATABASE=<koren-storitve>). Tako povezave različnih korenov storitve
imajo različne vrednosti in Access jih loči – tudi prek virov podatkov. Niza, ki ga Access prevzame brez povezovanja ali ga koda nastavi s TableDef.Connect,
gonilnik ne doseže; kdor take nize distribuira, DATABASE nastavi sam, za vsak koren storitve
drugače.
Opombe
Prednost. Vrednosti niza povezave imajo prednost pred vrednostmi vira podatkov. Ime in geslo, ki
ju aplikacija poda SQLConnect, veljata kot UID in PWD in imata prednost pred obojim.
Katera prijava velja.
| Podano | Prijava |
|---|---|
nobena od AUTH, UID, PWD | ključ storitve iz APIKEY/APIKEYENV, sicer nobena |
AUTH=WINDOWS | račun Windows aplikacije (HTTP Negotiate: Kerberos, sicer NTLM) |
UID (z AUTH=BASIC ali brez) | ime in geslo (HTTP Basic) |
AUTH=KEY | osebni ključ iz PWD, sicer iz upravitelja poverilnic |
Postopki so postopki HTTP: Basic po RFC 7617 (ime in geslo,
ki ju gonilnik kodira kot UTF-8), Negotiate po RFC 4559
(Kerberos ali NTLM prek prijave Windows). Ključ se pošlje v glavi, ki je ne določa noben standard;
njeno ime je nastavljivo (APIKEYHEADER). Kode 2FA so časovno odvisna enkratna gesla po
RFC 6238, kot jih ustvari aplikacija Authenticator;
gonilnik kodo samo posreduje, preveri jo storitev.
Podatkovni prehod Wkl.Data.Gateway osebni ključ sprejme tudi kot geslo HTTP Basic in pri tem imena
ne preverja. Njegova dokumentacija za to priporoča ime pkuser (UID=pkuser;PWD=wkl_…). S tem
gonilnikom je predvidena pot AUTH=KEY; pri njej gonilnik ključ pridobi tudi iz upravitelja poverilnic.
Geslo, ključ in seja samo prek zaščitene povezave. Geslo, osebni ključ in sejo gonilnik pošlje samo prek
https ali na lastni računalnik – na vsak naslov povezave, tudi na PASSTHROUGH. Sicer se povezava
konča z napako 28000; če storitev prek http zahteva 2FA, gonilnik ne pošlje ne kode ne
seje. Prijavo Windows (AUTH=WINDOWS) dobijo samo naslovi povezave. Preusmeritvi HTTP na drug
računalnik, druga vrata ali drugo shemo gonilnik ne sledi; glejte
Varnostni model.
Shranjeno geslo. Če nobeno mesto ne navaja gesla, gonilnik uporabi geslo, ki ga je uporabnik
shranil v pogovornem oknu. Shranjeno je v upravitelju poverilnic Windows pod ciljem
Wkl.Data.OData.Odbc:<ime>@<koren-storitve>, osebni ključ pod
Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@<koren-storitve>. Vir podatkov nikoli ne vsebuje gesla.
Nobenih gesel in ključev v povezavi Access. Access niz povezave povezane tabele shrani v datoteko
podatkovne zbirke; vsaka kopija datoteke bi s seboj nosila APIKEY ali PWD. Uporabite
AUTH=WINDOWS, AUTH=KEY s shranjenim ključem ali APIKEYENV. Geslo Access shrani samo, če je to pri
povezavi izrecno nastavljeno (dbAttachSavePWD).
2FA. Če storitev zahteva 2FA (401 z izzivom Wkl-Totp), aplikacija s
pogovornim oknom vpraša za kodo (glejte navodilo);
aplikacija brez njega uporabi TOTP ali SESSION ali pa dobi zavrnitev 28000 s sporočilom
storitve. Seja se pošilja v glavi X-Wkl-Session in velja za vse povezave procesa z isto prijavo.
Naslov, ki ga navaja izziv, mora imeti isti izvor kot URL; sicer gonilnik prijave ne pošlje tja.
Identiteta podatkovne zbirke (ROLE). Če storitev osebi ponuja več identitet (na primer skupni
prijavi vertrieb in marketing), gonilnik ime iz ROLE pošlje z vsako zahtevo (glava
X-Wkl-Role, odstotno kodirano). Če izbire ni ali ni dovoljena, storitev odgovori z 403 in
seznamom mogočih identitet (X-Wkl-Roles):
| Aplikacija | Vedenje |
|---|---|
s pogovornim oknom (okno podano, ne SQL_DRIVER_NOPROMPT) | izbirni seznam Identität wählen (Izberite identiteto) nad oknom aplikacije; zahteva se nato z izbiro pošlje znova – tudi pisalna, saj storitev zahtevo zavrne, preden karkoli izvede. Izbiro gonilnik vrne kot ROLE=; Access povezavo v prihodnje odpre z njo brez vprašanja |
| brez pogovornega okna (Power BI, Excel, skripti, ADO.NET) | zavrnitev 28000 s sporočilom storitve, ki navaja mogoče identitete; aplikacija poda ROLE= |
Izbirni seznam je lastno pogovorno okno po prijavi, ne del obrazca za prijavo: katere identitete storitev ponuja, je odvisno od tega, kdo se je prijavil.
Access deli povezave po DATABASE. Pravilo za nastavitev je v
Več korenov storitve v eni datoteki;
tu je podrobneje opisano, kako se vede Access. ACE za vse povezave procesa, katerih DATABASE se
glasi enako, odpre eno povezavo gonilnika – tisto, ki je bila odprta prva – in jo uporablja za
vse, ne glede na vrednosti drugih ključnih besed. Za dve povezavi iste tabele iz dveh korenov
storitve velja:
| Niza povezave se razlikujeta v … | Povezave | Rezultat |
|---|---|---|
URL in DATABASE (tudi tistem, ki ga dopolni gonilnik) | 2 | pravilno: vsaka povezava bere svoj koren storitve |
samo URL, DATABASE enak | 1 | napačno: obe bereta prvi koren storitve; Access celo prepiše shranjeni niz povezave druge povezane tabele s prvim URL |
samo DATABASE, URL enak | 2 | vsaka svoja povezava |
samo TIMEOUT | 1 | velja TIMEOUT prve povezave |
samo ROLE | 1 | obe delujeta z identiteto prve povezave, tudi pri pisanju |
samo PASSTHROUGH | 1 | glejte Nastavitev prepustnih poizvedb |
Posledice: dve različni storitvi ali korena storitve nikoli ne smeta imeti iste vrednosti
DATABASE. Druga identiteta (ROLE) v isti seji Access potrebuje lastno vrednost DATABASE, na
primer DATABASE=fachdaten-vertrieb; gonilnik vrednosti DATABASE sicer ne uporablja. Gonilnik o deljenju ne
izve ničesar in ga ne more preprečiti.
Viri podatkov (DSN, FILEDSN). Prek vira podatkov gonilnik vrne njegov DATABASE, sicer
koren storitve, pogovorno okno za nastavitev pa koren storitve zapiše v vsak nov ali spremenjen vir
podatkov. Dva vira podatkov za dva korena storitve imata tako različni vrednosti.
Časovne omejitve. Prekoračeno omejitev gonilnik javi kot HYT00, prav tako časovno omejitev
storitve (504). Zahteva s prekoračeno časovno omejitvijo se ne ponovi: storitev jo morda še obdeluje.
Prekinjena povezava. Če se povezava prekine brez odgovora, gonilnik zahtevo ponovi po 1 in 3 sekundah:
bralne zahteve vedno; ustvarjanje, spreminjanje, brisanje in lastni stavek, katerega rezultat se
prebere v celoti, z Idempotency-Key – storitev na ponovitev odgovori s shranjenim prvim odgovorom, torej brez drugega
zapisa in brez konflikta pri pisanju za spremembo, ki je uspela. Pretočnega lastnega stavka ne ponovi nikoli:
že prejetih vrstic ni mogoče preklicati; aplikacija dobi 08S01 namesto tiho skrajšanega rezultata.
Zaključka transakcije prav tako ne ponovi. Z RETRY=OFF ne ponovi ničesar. Katera
zaveza velja za katero storitev, je navedeno v
Zaveze glede na vrsto storitve.
Primer
Povezava brez gesel in ključev v datoteki, s prijavo Windows in prepustno potjo storitve:
ODBC;DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=WINDOWS
Z osebnim ključem, ki ga je uporabnik shranil v pogovornem oknu:
ODBC;DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=KEY
Skript brez pogovornega okna, ključ storitve iz okolja, prepustna pot izrecno izklopljena:
DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;APIKEYENV=FACHDATEN_SCHLUESSEL;PASSTHROUGH=OFF;TIMEOUT=120
Velja za
Gonilnik Wkl OData v 32- in 64-bitni različici (x86, x64); vsaka aplikacija ODBC. Okolja, ki jih
gonilnik podpira, so navedena v Predpogojih.
Izjeme
| SQLSTATE | Pogoj |
|---|---|
08001 | Niz povezave ni primeren za povezovanje: URL manjka ali ni naslov http/https; PASSTHROUGH, MAXURLLENGTH, TIMEOUT ali RETRY je neveljaven; ROLE daljši od 128 znakov. Sporočilo navede ključno besedo |
28000 | Prijavni podatki povezave v tej obliki niso uporabni: APIKEYENV navaja prazno spremenljivko; geslo, osebni ključ ali SESSION na nezaščiten naslov; protislovni prijavni podatki (spodaj); neznana vrednost AUTH. Nič ni poslano |
28000 | Storitev prijavo zavrne, aplikacija pa ne dovoli pogovornega okna – na primer ker manjka koda 2FA ali izbira identitete; sporočilo je sporočilo storitve |
08S01 | Storitev ni dosegljiva, tudi če povezava TLS ne uspe zaradi potrdila (glejte 08S01 "UntrustedRoot"), ali pa preusmerja na drug izvor |
HYT00 | prekoračena časovna omejitev, pri gonilniku ali pri storitvi (504) |
IM002 javi samo upravitelj gonilnikov: v okolju aplikacije (32- ali 64-bitnem) ne najde gonilnika
ali vira podatkov (glejte IM002: gonilnika ni mogoče najti).
Stanji 08001 („Client unable to establish connection“) in 28000 („Invalid authorization
specification“) sta tisti, ki ju za SQLDriverConnect predvideva specifikacija ODBC (Microsoft:
SQLDriverConnect, Diagnostics).
Z 28000 so zavrnjeni protislovni prijavni podatki, namesto da bi gonilnik po lastnem pravilu izbral
enega od njih: PWD brez
UID (razen pri AUTH=KEY), UID skupaj z AUTH=WINDOWS ali AUTH=KEY, AUTH=BASIC brez UID,
ime z dvopičjem (HTTP Basic pri dvopičju loči ime in geslo).
Glejte tudi
- Navodilo: Prijava z osebnim ključem in 2FA
- Navodilo: Nastavitev prepustnih poizvedb
- Koncept: Kako gonilnik prevaja stavke