Kusto-Verbindungszeichenfolgen
Kusto-Verbindungszeichenfolgen stellen die Informationen bereit, die für eine Kusto-Clientanwendung zum Herstellen einer Verbindung mit einem Kusto-Dienstendpunkt erforderlich sind. Kusto-Verbindungszeichenfolgen basieren auf dem ADO.NET-Verbindungszeichenfolgenmodell. Das heißt, das Verbindungszeichenfolge ist eine durch Semikolon getrennte Liste von Name-Wert-Parameterpaaren, die optional durch einen einzelnen URI präfixiert werden.
Die folgende Kusto-Verbindungszeichenfolge beginnt beispielsweise mit einem URI, der den Dienstendpunkt für die Kommunikation angibt: https://help.kusto.windows.net. Dieser URI wird der Data Source -Eigenschaft zugewiesen. /Samples Als Nächstes stellt die Verbindungszeichenfolge die Standarddatenbank dar und wird der Initial Catalog -Eigenschaft zugewiesen. Schließlich bieten zwei weitere Eigenschaften und FedAcceptweitere Konfigurations- oder Anpassungsoptionen für die Verbindung.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
Hinweis
- Bei Eigenschaftennamen wird die Groß-/Kleinschreibung nicht beachtet.
- Bei Eigenschaftswerten ist die Groß-/Kleinschreibung relevant.
- Leerzeichen zwischen Name-Wert-Parameterpaaren werden ignoriert.
- Eigenschaftswerte, die ein Semikolon (
;), ein einfaches Anführungszeichen (') oder ein doppeltes Anführungszeichen (") enthalten, müssen in doppelte Anführungszeichen eingeschlossen werden.
Mehrere Kusto-Clienttools unterstützen eine Erweiterung über dem URI-Präfix des Verbindungszeichenfolge, die ein Kurzformat von @ClusterName/InitialCatalog ermöglicht. Diese Tools übersetzen beispielsweise die Verbindungszeichenfolge @help/Samples in https://help.kusto.windows.net/Samples; Fed=true.
Programmgesteuert kann die C#- Kusto.Data.KustoConnectionStringBuilder Klasse Kusto-Verbindungszeichenfolgen analysieren und bearbeiten. Diese Klasse überprüft alle Verbindungszeichenfolgen und generiert eine Laufzeitausnahme, wenn die Überprüfung nicht erfolgreich ist. Diese Funktion ist in allen Varianten des Kusto SDK enthalten.
Vertrauenswürdige Endpunkte
Eine Verbindung mit einem Kusto-Endpunkt kann nur hergestellt werden, wenn dieser Endpunkt vertrauenswürdig ist.
Der Kusto-Client vertraut allen Endpunkten, deren Hostnamenteil vom Dienst ausgegeben wird.
Für instance Endpunkte, deren DNS-Hostname mit kusto.windows.netendet.
Standardmäßig stellt der Client keine Verbindungen mit anderen Endpunkten her. Um Verbindungen mit anderen Endpunkten zuzulassen, verwenden Sie die Kusto.Data.Common.KustoTrustedEndpoints -Klasse, um der Liste der vertrauenswürdigen Endpunkte Endpunkte hinzuzufügen. Verwenden Sie SetOverridePolicy , um die Standardrichtlinie zu überschreiben und AddTrustedHosts der vorhandenen Richtlinie neue Einträge hinzuzufügen.
KustoTrustedEndpoints.AddTrustedHosts(
new[]
{
// Allow an explicit service address
new FastSuffixMatcher.MatchRule("my-kusto.contoso.com", exact: true),
// Allow services whose DNS name end with ".contoso.com"
new FastSuffixMatcher.MatchRule(".contoso.com", exact: false),
}
);
Eigenschaften von Verbindungszeichenfolgen
In den folgenden Tabellen sind alle möglichen Eigenschaften aufgeführt, die in einem Kusto-Verbindungszeichenfolge enthalten sein können. Die Tabellen enthalten auch Aliasnamen für jede Eigenschaft. Darüber hinaus geben die Tabellen die programmgesteuerten Namen an, die jeder Eigenschaft zugeordnet sind, was den Namen der Eigenschaft im Kusto.Data.KustoConnectionStringBuilder -Objekt darstellt.
Allgemeine Eigenschaften
| Eigenschaftenname | Programmgesteuerter Name | BESCHREIBUNG |
|---|---|---|
| Clientversion für die Ablaufverfolgung | TraceClientVersion | Verwenden Sie beim Nachverfolgen der Clientversion diese Eigenschaft. |
| Datenquellenalias : Addr, Adresse, Netzwerkadresse, Server |
DataSource | Der URI, der den Kusto-Dienstendpunkt angibt. Beispiel: https://mycluster.kusto.windows.net. |
| Anfangskatalogalias : Datenbank |
InitialCatalog | Der Name der standardmäßig zu verwendenden Datenbank. Beispiel: MyDatabase. |
| Abfragekonsistenzalias : QueryConsistency |
QueryConsistency | Legen Sie entweder strongconsistency oder weakconsistency fest, ob die Abfrage vor der Ausführung mit den Metadaten synchronisiert werden soll. |
Eigenschaften für die Benutzerauthentifizierung
| Eigenschaftenname | Programmgesteuerter Name | BESCHREIBUNG |
|---|---|---|
| Microsoft Entra ID Verbundsicherheit Aliase: Verbundsicherheit, Federated, Fed, AADFed |
FederatedSecurity | Ein boolescher Wert, der den Client anweist, Microsoft Entra Authentifizierung auszuführen. |
| Autoritäts-ID-Alias : TenantId |
Authority | Ein Zeichenfolgenwert, der den Namen oder die ID des Mandanten des Benutzers bereitstellt. Standardwert: microsoft.com. Weitere Informationen finden Sie unter Microsoft Entra Autorität. |
| Erzwingen von MFA-Aliasen : MFA, EnforceMFA |
EnforceMfa | Ein optionaler boolescher Wert, der den Client anweist, ein mehrstufiges Authentifizierungstoken abzurufen. |
| Benutzer-ID-Aliase : UID, Benutzer |
UserID | Ein Zeichenfolgenwert, der den Client anweist, die Benutzerauthentifizierung mit dem angegebenen Benutzernamen durchzuführen. |
| Benutzername für die Ablaufverfolgung | TraceUserName | Ein optionaler Zeichenfolgenwert, der an den Dienst meldet, welcher Benutzername beim internen Ablaufen der Anforderung verwendet werden soll. |
| Benutzertokenalias : UsrToken, UserToken |
UserToken | Ein Zeichenfolgenwert, der den Client anweist, die Benutzerauthentifizierung mit dem angegebenen Bearertoken durchzuführen. Überschreibt ApplicationClientId, ApplicationKeyund ApplicationToken. Wenn angegeben, überspringt der tatsächliche Clientauthentifizierungsflow zugunsten des bereitgestellten Tokens. |
Unterstützte Eigenschaftenkombinationen für die Benutzerauthentifizierung
Geben Sie für die Benutzerauthentifizierung als trueanAAD Federated Security. Wählen Sie dann einen der folgenden Authentifizierungsmodi aus, und geben Sie die relevanten Eigenschaften für diesen Modus an.
| Authentifizierungsmodus | Eigenschaftennamen |
|---|---|
| Microsoft Entra Benutzereingabeaufforderungsauthentifizierung | - Benutzer-ID (optional) - Autoritäts-ID (optional) - Erzwingen von MFA (optional) - Benutzername für die Ablaufverfolgung (optional) |
| Microsoft Entra Benutzertokenauthentifizierung | - Benutzertoken : Erzwingen von MFA (optional) : Benutzername für die Ablaufverfolgung (optional) |
Eigenschaften für die Anwendungsauthentifizierung
| Eigenschaftenname | Programmgesteuerter Name | BESCHREIBUNG |
|---|---|---|
| Microsoft Entra ID Verbundsicherheit Aliase: Verbundsicherheit, Federated, Fed, AADFed |
FederatedSecurity | Ein boolescher Wert, der den Client anweist, Microsoft Entra-ID-Verbundauthentifizierung durchzuführen. |
| SendX5c-Aliase für Anwendungszertifikate: Anwendungszertifikat Senden eines öffentlichen Zertifikats, SendX5c |
ApplicationCertificateSendX5c | Ein boolescher Wert, der den Client anweist, antragstellername- und ausstellerbasierte Authentifizierung durchzuführen. |
| Anwendungszertifikatfingerabdruck - Alias: AppCert |
ApplicationCertificateThumbprint | Ein Zeichenfolgenwert, der den Fingerabdruck des Clientzertifikats bereitstellt, das bei Der Verwendung eines Anwendungsclientzertifikatauthentifizierungsflows verwendet werden soll. |
| Anwendungsclient-ID-Alias : AppClientId |
ApplicationClientId | Ein Zeichenfolgenwert, der die Anwendungsclient-ID bereitstellt, die bei der Authentifizierung verwendet werden soll. |
| Anwendungsschlüsselalias : AppKey |
ApplicationKey | Ein Zeichenfolgenwert, der den Anwendungsschlüssel bereitstellt, der bei der Authentifizierung mithilfe eines Anwendungsgeheimnisflows verwendet werden soll. |
| Anwendungsname für ablaufverfolgungsalias : TraceAppName |
ApplicationNameForTracing | Ein optionaler Zeichenfolgenwert, der an den Dienst meldet, welcher Anwendungsname bei der internen Ablaufverfolgung der Anforderung verwendet werden soll. |
| Anwendungstokenalias : AppToken |
ApplicationToken | Ein Zeichenfolgenwert, der den Client anweist, die Anwendungsauthentifizierung mit dem angegebenen Bearertoken durchzuführen. |
| Autoritäts-ID-Alias : TenantId |
Authority | Ein Zeichenfolgenwert, der den Namen oder die ID des Mandanten angibt, in dem die Anwendung registriert ist. Standardwert: microsoft.com. Weitere Informationen finden Sie unter Microsoft Entra Autorität. |
| Aliase der Azure-Region : AzureRegion, Region |
AzureRegion | Ein Zeichenfolgenwert, der den Namen der Azure-Region angibt, in der die Authentifizierung erfolgt. |
| ManagedServiceIdentity | EmbeddedManagedIdentity | Ein Zeichenfolgenwert, der den Client anweist, welche Anwendungsidentität bei der Authentifizierung der verwalteten Identität verwendet werden soll. Verwenden Sie system , um die systemseitig zugewiesene Identität anzugeben. Diese Eigenschaft kann nicht mit einem Verbindungszeichenfolge festgelegt werden, nur programmgesteuert. |
| Distinguished Name Alias des Antragstellers für Anwendungszertifikate: Antragsteller des Anwendungszertifikats |
ApplicationCertificateSubjectDistinguishedName | Ein Zeichenfolgenwert, der den distinguished Name des Antragstellers der Anwendung angibt. |
| Distinguished Name Alias des Anwendungszertifikatausstellers: Anwendungszertifikataussteller |
ApplicationCertificateIssuerDistinguishedName | Ein Zeichenfolgenwert, der den distinguished Name des Anwendungszertifikatausstellers angibt. |
Unterstützte Eigenschaftenkombinationen für die Anwendungsauthentifizierung
Geben Sie für die Anwendungsauthentifizierung als trueanAAD Federated Security. Wählen Sie dann einen der folgenden Authentifizierungsmodi aus, und geben Sie die relevanten Eigenschaften für diesen Modus an.
| Authentifizierungsmodus | Eigenschaftennamen |
|---|---|
| Authentifizierung mit Microsoft Entra-Anwendungsschlüsseln | – Anwendungsclient-ID – Anwendungsschlüssel – Autoritäts-ID – Anwendungsname für die Ablaufverfolgung (optional) |
| Microsoft Entra Anwendungsfingerabdruckauthentifizierung | – Anwendungsclient-ID – Anwendungszertifikatfingerabdruck – Autoritäts-ID – Anwendungsname für die Ablaufverfolgung (optional) |
| Microsoft Entra Antragsteller- und Ausstellerauthentifizierung | – Anwendungsclient-ID – Distinguished Name des Anwendungszertifikatsubjekts – Anwendungszertifikataussteller Distinguished Name – Autoritäts-ID – Azure-Region (optional) – Anwendungszertifikat SendX5c (optional) – Anwendungsname für die Ablaufverfolgung (optional) |
| Microsoft Entra Authentifizierung des Antragstellernamens der Anwendung | - Anwendungsclient-ID : Distinguished Name des Anwendungszertifikatsubjekts– Autoritäts-ID und Azure-Region (optional) – Anwendungsname für die Ablaufverfolgung (optional) |
| Microsoft Entra-Anwendungstokenauthentifizierung | – Anwendungstoken – Anwendungsname für die Ablaufverfolgung (optional) |
Authentifizierung mit einem Anwendungszertifikat
- Die Anwendung sollte so konfiguriert werden, dass sie das angegebene Zertifikat akzeptiert. Authentifizierung basierend auf Microsoft Entra Zertifikat der Anwendung.
- Die Anwendung sollte als autorisierter Prinzipal im entsprechenden Kusto-Cluster konfiguriert werden.
- Das Zertifikat muss im Lokalen Computerspeicher oder im Aktuellen Benutzerspeicher installiert werden.
- Der öffentliche Schlüssel des Zertifikats muss mindestens 2.048 Bits umfassen.
Eigenschaften für die Clientkommunikation
| Eigenschaftenname | Programmgesteuerter Name | BESCHREIBUNG |
|---|---|---|
| Akzeptieren | Akzeptieren | Ein boolescher Wert, der die Rückgabe detaillierter Fehlerobjekte bei Einem Fehler anfordert. |
| Streaming | Streaming | Ein boolescher Wert, der anfordert, dass der Client keine Daten sammelt, bevor er sie für den Aufrufer bereitstellt. Dies ist ein Standardverhalten. |
| Nicht komprimiert | Nicht komprimiert | Ein boolescher Wert, der anfordert, dass der Client keine Komprimierung auf Transportebene verlangt. |
Hinweis
Wenn das Streaming Flag aktiviert ist (wie es die Standardeinstellung ist), puffert das SDK nicht alle Antwortdaten im Arbeitsspeicher. Stattdessen "pullt" es die Daten aus dem Dienst, wenn der Aufrufer dies anfordert. Daher ist es in diesem Fall wichtig, dass der Aufrufer die Daten ordnungsgemäß entsorgt (z IDataReader. B. ), sobald er mit dem Lesen der Daten fertig ist, da die Netzwerkverbindung mit dem Dienst unnötigerweise offen gehalten wird.
Beispiele
Microsoft Entra ID-Verbundauthentifizierung mit der aktuell angemeldeten Benutzeridentität (der Benutzer wird bei Bedarf aufgefordert)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserPromptAuthentication(authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"
Microsoft Entra ID-Verbundauthentifizierung mit Benutzer-ID-Hinweis (Der Benutzer wird bei Bedarf aufgefordert)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var userId = "johndoe@contoso.com";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserPromptAuthentication(authority, userId);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority};User ID={userId}"
Microsoft Entra ID-Verbundanwendungsauthentifizierung mithilfe von ApplicationClientId und ApplicationKey
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appKey = "<appKey>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationKeyAuthentication(appId, appKey, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppKey={appKey};Authority Id={authority}"
Verwenden einer systemseitig zugewiesenen verwalteten Identität
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Verwenden einer benutzerseitig zugewiesenen verwalteten Identität
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Microsoft Entra-ID-Verbundauthentifizierung mithilfe des Benutzer-/Anwendungstokens
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var userAccessToken = "<userAccessToken>";
var appAccessToken = "<appAccessToken>";
// AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserTokenAuthentication(userAccessToken);
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;UserToken={userAccessToken}"
// AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationTokenAuthentication(appAccessToken);
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;ApplicationToken={appAccessToken}"
Verwenden des Tokenanbieterrückrufs (wird jedes Mal aufgerufen, wenn ein Token erforderlich ist)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadTokenProviderAuthentication(tokenProviderCallback);
Verwenden eines X.509-Zertifikats
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
X509Certificate2 appCert;
var authority = "contoso.com"; // Or the AAD tenant GUID
bool sendX5c; // Set to 'True' to use Trusted Issuer feature of AAD
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationCertificateAuthentication(appId, appCert, authority, sendX5c);
Verwenden eines X.509-Zertifikats nach Fingerabdruck (Client versucht, das Zertifikat aus dem lokalen Speicher zu laden)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appCert = "<appCert>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationThumbprintAuthentication(appId, appCert, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppCert={appCert};Authority Id={authority}"
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für