Verbindungseigenschaften eines Providers (Referenz)

Ein Provider beschreibt die Einstellungen seiner Verbindung als einzelne Eigenschaften. Ein Verwaltungsprogramm zeigt dafür Eingabefelder statt eines freien Textfelds für die Verbindungszeichenfolge. Die Zeichenfolge setzt der Provider selbst zusammen und prüft sie.

Syntax

Beschreibung lesen:

GET /admin/v1/odata/Providers?$filter=Usable eq true and Latest eq true
GET /admin/v1/odata/ProviderProperties?$filter=Provider eq 'sqlserver' and Language eq 'de'&$orderby=Scope,Position

Datenquelle mit Eigenschaften anlegen; ConnectionProperties ist ein JSON-Objekt als Text:

POST /admin/v1/odata/DataSources
Content-Type: application/json
 
{ "Name": "fachdaten", "Provider": "sqlserver",
  "ConnectionProperties": "{\"Data Source\":\"srv01\",\"Initial Catalog\":\"Fachdaten\",\"Integrated Security\":\"true\"}" }

Gelesen liefert DataSources dieselbe Form zurück, ohne geheime Werte:

{ "Name": "fachdaten", "Provider": "sqlserver", "Connection": null,
  "ConnectionProperties": "{\"Data Source\":\"srv01\",\"Initial Catalog\":\"Fachdaten\",\"Integrated Security\":\"true\"}" }

Parameter

Menge Providers

Nur lesen. Eine Zeile je installiertem Provider-Paket, verwendbar oder nicht.

Feld	Inhalt
`Id`, `PackageVersion`	Schlüssel: Kennung des Providers (`sqlserver`) und Version des Pakets
`Name`, `Vendor`	Anzeigename und Hersteller laut Paket
`Aliases`	Weitere Namen, durch Komma getrennt (nur mitgelieferte Pakete, etwa `mssql`)
`ContractMin`, `ContractBelow`	Bereich des Provider-Vertrags, für den das Paket gebaut ist
`BuiltIn`	Mit dem Dienst geliefert (`true`) oder vom Betreiber installiert
`Usable`, `Problem`	Ob das Paket die Prüfungen besteht; sonst der Grund
`Latest`	Die höchste verwendbare Version dieser Kennung: die Version, die eine Datenquelle ohne `ProviderVersion` bekommt
`DescribesConnection`	Ob der Provider seine Verbindungseigenschaften beschreibt; sonst bleibt nur die Zeichenfolge (`Connection`)

Menge ProviderProperties

Nur lesen. Je verwendbarem Paket, das seine Verbindung beschreibt: eine Zeile je Eigenschaft, Bereich und Sprache.

Feld	Inhalt
`Provider`, `PackageVersion`, `Scope`, `Name`, `Language`	Schlüssel. `Scope`: `Connection` (Verbindung) oder `Options` (Provider-Einstellungen, `ProviderOptions`). `Language`: zweistelliger Code; jede Eigenschaft gibt es mindestens in `en`
`Position`	Reihenfolge innerhalb des Bereichs, ab 1
`Type`	`Text`, `Integer` (nur Ziffern), `Boolean` (`true`/`false`) oder `Choice`
`Label`, `Description`	Beschriftung und Erklärung in dieser Sprache; fehlt die Sprache beim Provider, die englische
`Required`	Ob eine Verbindung den Wert braucht
`Default`	Wert, der ohne Angabe gilt, als Text; leer, wenn keiner gilt
`Choices`	Bei `Choice`: die erlaubten Werte als JSON-Liste, etwa `["True","False","Strict"]`
`Secret`	Ein Geheimnis (Kennwort): wird geschrieben, nie zurückgegeben
`Category`	Gruppe für die Anzeige, etwa `Server`, `Security`, `Advanced`

Das Lesen von ProviderProperties lädt jedes verwendbare Paket, das noch nicht geladen ist: Die Beschreibung ist Code des Providers.

Felder von DataSources

Feld	Bedeutung
`Provider`	Kennung des Providers; leer: es gilt `Dialect`
`ProviderVersion`	Feste Version des Pakets; leer: die höchste verwendbare
`ProviderOptions`	Provider-Einstellungen als JSON-Objekt aus Texten, etwa `{"Modus":"schnell"}`; leer, wenn der Provider keine kennt
`Connection`	Verbindungszeichenfolge als Text; nur schreibbar, liest sich leer
`ConnectionProperties`	Verbindung als JSON-Objekt aus Eigenschaft und Wert, als Text. Geschrieben: der Provider setzt daraus die Zeichenfolge zusammen. Gelesen: die Eigenschaften der gespeicherten Verbindung ohne geheime Werte

Die Bedeutung von Provider, ProviderVersion und ProviderOptions ist dieselbe wie in der Datei, siehe Konfiguration.

Eigenschaften von sqlserver

Der mitgelieferte SQL-Server-Provider beschreibt diese Eigenschaften; ProviderOptions kennt er keine. Die Namen sind die Schlüsselwörter, die der SQL-Server-Treiber in eine Zeichenfolge schreibt. Vorgaben und erlaubte Werte stammen aus dem Treiber selbst; maßgeblich ist ProviderProperties.

Name	Typ	Kategorie	Pflicht	Bedeutung
`Data Source`	Text	Server	ja	Server, mit Instanz (`srv01\prod`) oder Port (`srv01,1433`)
`Initial Catalog`	Text	Server	ja	Datenbank, die der Dienst unter dem Alias anbietet
`Failover Partner`	Text	Server		Spiegelserver bei Datenbankspiegelung
`Multi Subnet Failover`	Boolean	Server		Verfügbarkeitsgruppe über mehrere Subnetze
`Application Intent`	Choice	Server		`ReadWrite` (Vorgabe) oder `ReadOnly` (lesbares Replikat)
`Integrated Security`	Boolean	Security		Windows-Anmeldung unter dem Dienstkonto
`Authentication`	Choice	Security		Verfahren für Microsoft Entra ID, etwa `ActiveDirectoryIntegrated`; leer für SQL- oder Windows-Anmeldung
`User ID`	Text	Security		SQL-Anmeldung
`Password`	Text	Security		Kennwort der SQL-Anmeldung; geheim
`Encrypt`	Choice	Security		`True` (Vorgabe), `False` oder `Strict`
`Trust Server Certificate`	Boolean	Security		Zertifikat des Servers ohne Prüfung annehmen; nur für Testumgebungen
`Host Name In Certificate`	Text	Security		Erwarteter Name im Zertifikat
`Application Name`	Text	Advanced		Name der Verbindung auf dem Server; ohne Angabe `Wkl.Data.Gateway`
`Connect Timeout`	Integer	Advanced		Sekunden bis zum Abbruch des Verbindungsaufbaus (Vorgabe 15)
`Command Timeout`	Integer	Advanced		Vorgabe in Sekunden für Anweisungen; die Grenzen des Dienstes gehen vor

Nicht angeboten sind Einstellungen, die der Dienst selbst führt (Pooling, Poolgrößen, MultipleActiveResultSets). Eine von Hand geschriebene Zeichenfolge darf sie enthalten; als Eigenschaften erscheinen sie dann nicht.

Bemerkungen

Wer die Zeichenfolge baut. Der Provider der Datenquelle – Provider, sonst Dialect – setzt aus den Eigenschaften die Zeichenfolge zusammen und prüft sie. Das Verwaltungsprogramm braucht kein Wissen über die Schlüsselwörter einer Datenbank. Der Dienst versiegelt die Zeichenfolge wie eine als Text gesendete.

Schreiben. Connection und ConnectionProperties zugleich lehnt der Dienst mit 400 ab, ebenso einen Provider ohne Beschreibung (DescribesConnection = false). Werte dürfen JSON-Texte, -Zahlen oder true/false sein; null oder ein leerer Text entfernt die Eigenschaft. Eine unbekannte Eigenschaft, ein fehlender Pflichtwert oder ein Wert falschen Typs ergibt 400; die Meldung nennt die Eigenschaft, nie ihren Wert.

Kennwort beim Ändern. Fehlt eine geheime Eigenschaft in ConnectionProperties, behält der Dienst ihren gespeicherten Wert: Wer nur den Server ändert, gibt das Kennwort nicht erneut ein. Ein ausdrücklich leerer Wert ("Password": "") entfernt es. Alle anderen Eigenschaften ersetzen die gespeicherte Verbindung als Ganzes; was fehlt, gilt danach mit seiner Vorgabe.

Lesen. ConnectionProperties enthält die gesetzten Eigenschaften der gespeicherten Verbindung, nie eine geheime. Leer bleibt das Feld, wenn der Provider keine Beschreibung hat oder eine von Hand geschriebene Zeichenfolge nicht zerlegen kann; ändern lässt sich die Verbindung dann über Connection. Das Feld gehört nicht zur Zeilenversion; die Version folgt der versiegelten Zeichenfolge.

Änderungsprotokoll. ConnectionProperties erscheint dort nur als „neu gesetzt“, wie Connection.

Beispiel

Ein Verwaltungsprogramm füllt die Auswahl der Provider und ein Eigenschaftenraster:

Providers mit Usable eq true and Latest eq true lesen und die Auswahl füllen (Name, Wert Id).
Zur gewählten Id ProviderProperties mit Scope eq 'Connection' und der eigenen Sprache lesen, nach Position ordnen, je Category gruppieren; Choice als Auswahl, Boolean als Schalter, Secret als Kennwortfeld.
Beim Bearbeiten ConnectionProperties der Datenquelle lesen und die Felder vorbelegen; das Kennwortfeld bleibt leer.
Speichern: nur die ausgefüllten Felder als JSON-Objekt in ConnectionProperties senden, das leere Kennwortfeld nicht – dann bleibt das gespeicherte Kennwort.
Mit `test-connection` prüfen.

Siehe auch