Verbindungszeichenfolge des Treibers (Referenz)
Die Verbindungszeichenfolge – oder die gleichnamigen Werte einer Datenquelle (DSN) – legt fest, an welchen OData-Dienst der Treiber sich wendet und wie er sich anmeldet. Diese Seite nennt jedes Schlüsselwort mit Vorgabe und Wirkung; Sie brauchen sie, wenn Sie eine Verknüpfung per Code anlegen, eine Datenquelle verteilen oder eine Verbindung in .NET oder VBA aufbauen.
Syntax
DRIVER={Wkl OData};URL=<Dienststamm>[;<Schlüsselwort>=<Wert>]…
DSN=<Name der Datenquelle>[;<Schlüsselwort>=<Wert>]…
Groß- und Kleinschreibung der Schlüsselwörter zählt nicht. Ein Wert mit Semikolon steht in
geschweiften Klammern, wie bei jedem ODBC-Treiber. Die Form der Zeichenfolge und die Rollen von
DRIVER, DSN, UID und PWD legt die ODBC-Spezifikation fest (Microsoft:
SQLDriverConnect);
alle übrigen Schlüsselwörter sind die dieses Treibers.
Pflicht ist nur URL (oder eine Datenquelle, die sie nennt).
Parameter
| Schlüsselwort | Vorgabe | Bedeutung |
|---|---|---|
DRIVER | – | Registrierter Name des Treibers, {Wkl OData}. Pflicht, wenn kein DSN genannt ist |
DSN | – | Datenquelle, aus der der Treiber die übrigen Werte liest |
FILEDSN | – | Dateidatenquelle; der Treibermanager liest sie und reicht ihre Werte weiter |
DESCRIPTION | – | Beschreibung einer Datenquelle im Einrichtungsdialog; ohne Wirkung auf die Verbindung |
URL | – | Stammadresse des Dienstes, unter der $metadata liegt, http oder https. Pflicht; fehlt sie, scheitert die Verbindung mit 08001 |
DATABASE | Wert der Datenquelle, sonst Dienststamm | Trennt die Verbindungen in Access; ergänzt der Treiber selbst, siehe Rückgabewert. Der Einrichtungsdialog schreibt ihn in jede Datenquelle |
AUTH | – | Anmeldeverfahren: WINDOWS, BASIC oder KEY. Ein anderer Wert verhindert die Verbindung |
UID | – | Name einer Anmeldung mit Kennwort (HTTP Basic), etwa einer SQL-Server-Anmeldung, die der Dienst prüft |
PWD | leer | Kennwort zu UID; bei AUTH=KEY der persönliche Schlüssel |
SAVEPWD | – | Schreibt nur der Einrichtungsdialog: 1, wenn „Kennwort speichern“ bzw. „Schlüssel speichern“ angekreuzt war. Der Wert selbst landet in der Windows-Anmeldeinformationsverwaltung, nie in der Datenquelle |
APIKEY | – | Dienstschlüssel im Klartext. Nicht für Verknüpfungen in Access, siehe Bemerkungen |
APIKEYENV | – | Name einer Umgebungsvariablen, die den Dienstschlüssel trägt. Ist sie leer, scheitert die Verbindung mit 28000 |
APIKEYHEADER | X-Api-Key | Kopfzeile, in der Dienstschlüssel und persönlicher Schlüssel reisen |
TOTP | – | Code eines zweiten Faktors für die erste Herausforderung des Dienstes, für Anwendungen ohne Dialog. Gilt einmal und 30 Sekunden |
SESSION | – | Sitzung eines zweiten Faktors, die die Anwendung selbst eröffnet hat. Nur über https oder an den eigenen Rechner |
ROLE | – | Datenbank-Identität, unter der der Dienst die Anweisungen ausführt, wenn er mehrere anbietet. Höchstens 128 Zeichen; kein Geheimnis |
APP | – | Anwendung und ihre Version als <Produkt>/<Version>, etwa APP=Kundenverwaltung/2.4.1. Der Treiber sendet sie mit jeder Anfrage im Kopf X-Wkl-Application; ein Dienst mit Datenbank-Updates hält damit ein Update zurück, das ältere Versionen bricht, solange eine solche noch fragt. Produkt aus Buchstaben, Ziffern, ., - und _, höchstens 64 Zeichen; Version aus zwei bis vier Zahlen. Ein Wert anderer Form, etwa APP=Microsoft Office aus einer SQL-Server-Verknüpfung, wird nicht gesendet, die Verbindung gelingt trotzdem (Zeile in der Ablaufverfolgung). Eine Angabe der Anwendung, kein Nachweis |
PASSTHROUGH | Angabe des Dienstes | Adresse für Anweisungen, die sich nicht in OData übersetzen lassen; absolut oder relativ zum Dienststamm. Fehlt sie, gilt die Adresse, die der Dienst in $metadata nennt (Store.PassThrough) – aber nur mit demselben Schema, Rechner und Port wie URL, damit ein Schemadokument die Anmeldung nicht anderswohin lenken kann. OFF schaltet beides ab |
TIMEOUT | 60 | Sekunden je Anfrage, wenn die Anwendung für die Anweisung keine Zeitgrenze setzt; 0 heißt ohne Grenze. Eine negative Zahl oder ein Text: Verbindung scheitert mit 08001. Eine Zeitgrenze der Anwendung (SQL_ATTR_QUERY_TIMEOUT, in ADO.NET CommandTimeout) geht vor; setzt die Anwendung dort 0, gilt keine Grenze |
RETRY | ON | OFF meldet eine abgebrochene Verbindung sofort als 08S01, statt die Anfrage zu wiederholen; für einen Dienst, der Idempotency-Key nicht einhält. Auch auf einen ausgelasteten Dienst (429, 503) wartet der Treiber dann nicht. Ein anderer Wert: 08001 |
MAXURLLENGTH | 2000 | Längste Adresse einer Leseanfrage. Eine längere geht als POST …/$query mit den Optionen im Rumpf; 0 schickt jede Leseanfrage mit Optionen so. Keine Zahl: Verbindung scheitert mit 08001 |
TRACEFILE | – | Datei für die Ablaufverfolgung des Treibers, siehe Ablaufverfolgung |
Umgebungsvariablen, die der Treiber außerdem liest:
| Variable | Wirkung |
|---|---|
WKL_ODATA_ODBC_TRACE | Datei für die Ablaufverfolgung, wenn die Verbindung kein TRACEFILE nennt |
WKL_ODBC_DIALOG_THEME | light oder dark: Darstellung der Dialoge unabhängig vom App-Modus von Windows |
Rückgabewert
SQLDriverConnect gibt die Verbindungszeichenfolge so zurück, wie sie kam, mit vier Ausnahmen.
Access speichert beim Verknüpfen diese zurückgegebene Zeichenfolge in der verknüpften Tabelle; eine
Zeichenfolge, die Code später selbst setzt (TableDef.Connect mit RefreshLink), bleibt wie gesetzt.
TOTP und SESSION fehlen. Die Zeichenfolge, die Access zu einer verknüpften Tabelle
speichert, enthält sie nicht, und die Ablaufverfolgung zeigt ihre Werte nicht.
ROLE wird ergänzt, wenn der Benutzer im Dialog eine Identität gewählt hat.
Nach dem Anmeldedialog gibt der Treiber die Angaben zurück, die der Benutzer im Dialog stehen
ließ, etwa AUTH und UID. Es fehlen APIKEY, außer die Anwendung hat ihn selbst übergeben, das
Kennwort, wenn der Benutzer es in der Anmeldeinformationsverwaltung gespeichert hat, und Werte, die
unverändert schon in der Datenquelle stehen.
DATABASE wird ergänzt. Nennt die Zeichenfolge kein DATABASE, hängt der Treiber eines an: den
Wert, den die Datenquelle speichert, sonst den Dienststamm (DATABASE=<Dienststamm>). Damit tragen
Verknüpfungen verschiedener Dienststämme verschiedene Werte, und Access trennt sie – auch über
Datenquellen. Eine Zeichenfolge, die Access übernimmt, ohne zu
verbinden, oder die Code mit TableDef.Connect setzt, erreicht der Treiber nicht; wer solche
Zeichenfolgen verteilt, setzt DATABASE selbst, je Dienststamm verschieden.
Bemerkungen
Vorrang. Werte der Verbindungszeichenfolge gehen denen der Datenquelle vor. Name und Kennwort,
die eine Anwendung SQLConnect übergibt, gelten als UID und PWD und gehen beiden vor.
Welche Anmeldung gilt.
| Angaben | Anmeldung |
|---|---|
keine von AUTH, UID, PWD | Dienstschlüssel aus APIKEY/APIKEYENV, sonst keine |
AUTH=WINDOWS | Windows-Konto der Anwendung (HTTP Negotiate: Kerberos, sonst NTLM) |
UID (mit oder ohne AUTH=BASIC) | Name und Kennwort (HTTP Basic) |
AUTH=KEY | persönlicher Schlüssel aus PWD, sonst aus der Anmeldeinformationsverwaltung |
Die Verfahren sind die von HTTP: Basic nach RFC 7617
(Name und Kennwort, vom Treiber als UTF-8 kodiert), Negotiate nach
RFC 4559 (Kerberos oder NTLM über die Windows-Anmeldung).
Ein Schlüssel reist in einer Kopfzeile, die kein Standard festlegt; ihr Name ist einstellbar
(APIKEYHEADER). Die Codes des zweiten Faktors sind zeitbasierte Einmalkennwörter nach
RFC 6238, wie sie eine Authenticator-App erzeugt; der
Treiber reicht den Code nur weiter, prüfen tut ihn der Dienst.
Der Datendienst Wkl.Data.Gateway nimmt einen persönlichen Schlüssel auch als Kennwort von HTTP Basic an
und prüft den Namen dabei nicht. Seine Dokumentation empfiehlt dafür den Namen pkuser
(UID=pkuser;PWD=wkl_…). Mit diesem Treiber ist AUTH=KEY der vorgesehene Weg; damit holt er den
Schlüssel auch aus der Anmeldeinformationsverwaltung.
Kennwort, Schlüssel und Sitzung nur geschützt. Ein Kennwort, einen persönlichen Schlüssel und
eine Sitzung sendet der Treiber nur über https oder an den eigenen Rechner – an jede Adresse der
Verbindung, auch an PASSTHROUGH. Sonst scheitert die Verbindung mit 28000; verlangt ein Dienst
über http einen zweiten Faktor, sendet der Treiber weder Code noch Sitzung. Die Windows-Anmeldung
(AUTH=WINDOWS) erhalten nur die Adressen der Verbindung. Einer HTTP-Umleitung an einen anderen
Rechner, Port oder ein anderes Schema folgt der Treiber nicht; siehe
Sicherheitsmodell.
Gespeichertes Kennwort. Nennt keine Stelle ein Kennwort, nimmt der Treiber das, das der Benutzer
im Dialog gespeichert hat. Es liegt in der Windows-Anmeldeinformationsverwaltung unter dem Ziel
Wkl.Data.OData.Odbc:<Name>@<Dienststamm>. Ein persönlicher Schlüssel gilt für die Person am ganzen
Dienst und liegt deshalb eine Ebene höher: unter Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@<Datenquelle>;
beim Datendienst Wkl.Data.Gateway ist das die Adresse der Datenquelle (…/odata/v4/<Alias>/). Alle Schemas einer
Datenquelle finden so denselben Schlüssel. Ein Eintrag am Dienststamm selbst (aus Version 0.8.4 und früher)
gilt weiter und geht vor. Ein Datenquellenname (DSN) speichert nie ein Kennwort.
Kein Geheimnis in einer Access-Verknüpfung. Access speichert die Verbindungszeichenfolge einer
verknüpften Tabelle in der Datenbankdatei; jede Kopie der Datei trüge APIKEY oder PWD mit sich.
Verwenden Sie AUTH=WINDOWS, AUTH=KEY mit gespeichertem Schlüssel oder APIKEYENV. Ein Kennwort
speichert Access nur, wenn die Verknüpfung es ausdrücklich soll (dbAttachSavePWD).
Zweiter Faktor. Verlangt der Dienst einen zweiten Faktor (401 mit der Herausforderung
Wkl-Totp), fragt eine Anwendung mit Dialog den Code ab (siehe
Anleitung); eine ohne Dialog verwendet
TOTP oder SESSION oder erhält die Ablehnung 28000 mit der Meldung des Dienstes. Die Sitzung
reist in der Kopfzeile X-Wkl-Session und gilt für alle Verbindungen des Prozesses mit derselben
Anmeldung. Die Adresse, die die Herausforderung nennt, muss denselben Ursprung haben wie URL;
sonst schickt der Treiber die Anmeldung nicht dorthin.
Datenbank-Identität (ROLE). Bietet der Dienst einer Person mehrere Identitäten an (etwa die
gemeinsamen Anmeldungen vertrieb und marketing), schickt der Treiber den Namen aus ROLE mit
jeder Anfrage (Kopfzeile X-Wkl-Role, prozentkodiert). Fehlt die Wahl oder ist sie nicht erlaubt,
antwortet der Dienst 403 mit der Liste der möglichen (X-Wkl-Roles):
| Anwendung | Verhalten |
|---|---|
mit Dialog (Fenster übergeben, nicht SQL_DRIVER_NOPROMPT) | Auswahlliste Identität wählen auf dem Fenster der Anwendung; die Anfrage geht danach mit der Wahl erneut – auch eine schreibende, denn der Dienst lehnt ab, bevor er etwas ausführt. Die Wahl gibt der Treiber als ROLE= zurück; Access öffnet die Verknüpfung künftig ohne Rückfrage mit ihr |
| ohne Dialog (Power BI, Excel, Skripte, ADO.NET) | Ablehnung 28000 mit der Meldung des Dienstes, die die möglichen Identitäten nennt; die Anwendung gibt ROLE= mit |
Die Auswahlliste ist ein eigener Dialog nach der Anmeldung, nicht Teil des Anmeldeformulars: Welche Identitäten der Dienst anbietet, hängt davon ab, wer sich angemeldet hat.
Access teilt Verbindungen nach DATABASE. Die Regel für die Einrichtung steht unter
Mehrere Dienststämme in einer Datei;
hier das Verhalten von Access im Einzelnen. ACE öffnet für alle Verknüpfungen eines Prozesses,
deren DATABASE gleich lautet, eine Verbindung des Treibers – die zuerst geöffnete – und
verwendet sie für alle, gleich was die übrigen Schlüsselwörter sagen. Für zwei Verknüpfungen
derselben Tabelle aus zwei Dienststämmen gilt:
| Die beiden Verbindungszeichenfolgen unterscheiden sich in … | Verbindungen | Ergebnis |
|---|---|---|
URL und DATABASE (auch das vom Treiber ergänzte) | 2 | richtig: Jede Verknüpfung liest ihren Dienststamm |
nur URL, DATABASE gleich | 1 | falsch: Beide lesen den ersten Dienststamm; Access schreibt sogar die gespeicherte Verbindung der zweiten Verknüpfung auf die erste URL um |
nur DATABASE, URL gleich | 2 | je eigene Verbindung |
nur TIMEOUT | 1 | es gilt der TIMEOUT der ersten Verbindung |
nur ROLE | 1 | beide laufen unter der Identität der ersten Verbindung, auch beim Schreiben |
nur PASSTHROUGH | 1 | siehe Pass-Through-Abfragen einrichten |
Folgen: Zwei verschiedene Dienste oder Dienststämme dürfen nie denselben DATABASE-Wert tragen.
Eine zweite Identität (ROLE) in derselben Access-Sitzung braucht einen eigenen DATABASE-Wert,
etwa DATABASE=fachdaten-vertrieb; der Treiber wertet DATABASE sonst nicht aus. Der Treiber
erfährt von der Teilung nichts und kann sie nicht verhindern.
Datenquellen (DSN, FILEDSN). Über eine Datenquelle gibt der Treiber deren DATABASE zurück,
sonst den Dienststamm, und der Einrichtungsdialog schreibt den Dienststamm in jede neue oder
geänderte Datenquelle. Zwei Datenquellen auf zwei Dienststämme tragen damit verschiedene Werte.
Zeitgrenzen. Eine überschrittene Grenze meldet der Treiber als HYT00, ebenso die Zeitgrenze des
Dienstes (504). Eine abgelaufene Zeitgrenze wird nicht wiederholt: Der Dienst arbeitet dann
womöglich noch.
Unterbrochene Verbindung. Bricht die Verbindung ohne Antwort ab, wiederholt der Treiber nach 1 und
3 Sekunden: Lesen immer; Anlegen, Ändern, Löschen und eine gesammelt gelesene eigene Anweisung mit
Idempotency-Key – der Dienst beantwortet die Wiederholung mit der gespeicherten ersten Antwort, also
kein zweiter Satz und kein Schreibkonflikt für eine Änderung, die durchging. Eine gestreamte eigene
Anweisung nie: Gelieferte Zeilen lassen sich nicht zurücknehmen; die Anwendung erhält 08S01 statt
eines stillschweigend gekürzten Ergebnisses. Den Abschluss einer Transaktion wiederholt er ebenfalls
nicht. Mit RETRY=OFF wiederholt er gar nicht. Welche Zusage für welchen Dienst gilt, steht unter
Zusagen je Art des Dienstes.
Beispiel
Verknüpfung ohne Geheimnis in der Datei, mit Windows-Anmeldung und Durchreiche des Dienstes:
ODBC;DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=WINDOWS
Mit persönlichem Schlüssel, den der Benutzer im Dialog gespeichert hat:
ODBC;DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=KEY
Skript ohne Dialog, Dienstschlüssel aus der Umgebung, Durchreiche ausdrücklich abgeschaltet:
DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;APIKEYENV=FACHDATEN_SCHLUESSEL;PASSTHROUGH=OFF;TIMEOUT=120
Gilt für
Treiber Wkl OData in beiden Bitbreiten (x86, x64); jede ODBC-Anwendung. Für welche Umgebungen der
Treiber freigegeben ist, steht unter
Voraussetzungen.
Ausnahmen
| SQLSTATE | Bedingung |
|---|---|
08001 | Die Verbindungszeichenfolge taugt nicht zum Verbinden: URL fehlt oder ist keine http-/https-Adresse; PASSTHROUGH, MAXURLLENGTH, TIMEOUT oder RETRY ist ungültig; ROLE länger als 128 Zeichen. Die Meldung nennt das Schlüsselwort |
28000 | Die Anmeldeangaben der Verbindung sind so nicht verwendbar: APIKEYENV nennt eine leere Variable; Kennwort, persönlicher Schlüssel oder SESSION an eine ungeschützte Adresse; widersprüchliche Anmeldeangaben (unten); unbekannter Wert von AUTH. Nichts ist gesendet |
28000 | Der Dienst lehnt die Anmeldung ab, und die Anwendung erlaubt keinen Dialog – etwa wegen eines fehlenden zweiten Faktors oder einer fehlenden Identitätswahl; die Meldung ist die des Dienstes |
08S01 | Der Dienst ist nicht erreichbar, auch wenn die TLS-Verbindung am Zertifikat scheitert (siehe 08S01 „UntrustedRoot“), oder er leitet an einen anderen Ursprung um |
HYT00 | Zeitgrenze überschritten, beim Treiber oder beim Dienst (504); oder der Dienst blieb ausgelastet (429), nachdem der Treiber gewartet hat |
IM002 meldet nur der Treibermanager: Er findet für die Bitbreite der Anwendung den Treiber oder
die Datenquelle nicht (siehe IM002: Der Treiber wird nicht gefunden).
Die Zustände 08001 („Client unable to establish connection“) und 28000 („Invalid authorization
specification“) sind die, die die ODBC-Spezifikation für SQLDriverConnect vorsieht (Microsoft:
SQLDriverConnect, Diagnostics).
Abgewiesen mit 28000, statt nach einer Regel des Treibers entschieden: PWD ohne UID (außer bei
AUTH=KEY), UID zusammen mit AUTH=WINDOWS oder AUTH=KEY, AUTH=BASIC ohne UID, ein Name mit
Doppelpunkt (HTTP Basic trennt Name und Kennwort daran).
Siehe auch
- Anleitung: Pass-Through-Abfragen einrichten
- Einführung: Eine Tabelle in Access verknüpfen