Kusto-anslutningssträngar

  • Artikel

Kusto-anslutningssträngar tillhandahåller den information som krävs för att ett Kusto-klientprogram ska kunna upprätta en anslutning till en Kusto-tjänstslutpunkt. Kusto-anslutningssträngar modelleras efter ADO.NET anslutningssträngar. Det vill: anslutningssträng är en semikolonavgränsad lista med namn/värde-parameterpar, som eventuellt föregås av en enda URI.

Följande Kusto-anslutningssträng börjar till exempel med en URI som anger tjänstslutpunkten för kommunikation: https://help.kusto.windows.net. Den här URI:n tilldelas egenskapen Data Source . /Samples I anslutningssträng representerar sedan standarddatabasen och tilldelas till Initial Catalog egenskapen . Slutligen tillhandahåller två andra egenskaper, Fed och Accept, ytterligare konfigurations- eller anpassningsalternativ för anslutningen.

https://help.kusto.windows.net/Samples; Fed=true; Accept=true

Anteckning

  • Egenskapsnamn är inte skiftlägeskänsliga.
  • Egenskapsvärden är skiftlägeskänsliga.
  • Blanksteg mellan namn/värde-parameterpar ignoreras.
  • Ett egenskapsvärde som innehåller semikolon (;), ett enkelt citattecken (') eller ett dubbelt citattecken (") måste omges av dubbla citattecken.

Flera Kusto-klientverktyg stöder ett tillägg över URI-prefixet för anslutningssträng som möjliggör ett kortformat av @ClusterName/InitialCatalog. De här verktygen översätter till exempel anslutningssträng @help/Samples till https://help.kusto.windows.net/Samples; Fed=true.

Programmässigt kan C# Kusto.Data.KustoConnectionStringBuilder -klassen parsa och ändra Kusto-anslutningssträngar. Den här klassen validerar alla anslutningssträngar och genererar ett körningsund undantag om valideringen misslyckas. Den här funktionen finns i alla varianter av Kusto SDK.

Betrodda slutpunkter

En anslutning med en Kusto-slutpunkt kan bara upprättas om slutpunkten är betrodd. Kusto-klienten litar på alla slutpunkter vars värdnamnsdel utfärdas av tjänsten. Till exempel slutpunkter vars DNS-värdnamn slutar med kusto.windows.net.

Som standard upprättar klienten inte anslutningar till andra slutpunkter. För att tillåta anslutningar till andra slutpunkter använder du Kusto.Data.Common.KustoTrustedEndpoints klassen för att lägga till slutpunkter i listan över betrodda slutpunkter. Använd SetOverridePolicy för att åsidosätta standardprincipen och AddTrustedHosts för att lägga till nya poster i den befintliga principen.

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),
    }
);

Egenskaper för anslutningssträngen

I följande tabeller visas alla möjliga egenskaper som kan ingå i en Kusto-anslutningssträng. Tabellerna innehåller även aliasnamn för varje egenskap. Dessutom anger tabellerna de programmässiga namn som är associerade med varje egenskap, som representerar namnet på egenskapen i Kusto.Data.KustoConnectionStringBuilder objektet.

Allmänna egenskaper

Egenskapsnamn Programmatiskt namn Description
Klientversion för spårning TraceClientVersion Använd den här egenskapen när du spårar klientversionen.
Alias för datakälla

: Addr, Address, Network Address, Server		 Datakälla URI:n som anger Kusto-tjänstslutpunkten. Till exempel https://mycluster.kusto.windows.net.
Initialtkatalogalias

: Databas		 InitialCatalog Namnet på databasen som ska användas som standard. Till exempel MyDatabase.
Alias för frågekonsekvens

: QueryConsistency		 QueryConsistency Ange till antingen strongconsistency eller weakconsistency för att avgöra om frågan ska synkroniseras med metadata innan den körs.

Egenskaper för användarautentisering

Egenskapsnamn Programmatiskt namn Description
federerad säkerhet

för Microsoft Entra-IDAlias: Federerad säkerhet, federerad, Fed, AADFed		 Federerad säkerhet Ett booleskt värde som instruerar klienten att utföra Microsoft Entra autentisering.
Alias för utfärdar-ID

: TenantId		 Myndighet Ett strängvärde som anger namnet eller ID:t för användarens klientorganisation. Standardvärdet är microsoft.com. Mer information finns i Microsoft Entra utfärdare.
Framtvinga MFA-alias

: MFA, EnforceMFA		 EnforceMfa Ett valfritt booleskt värde som instruerar klienten att hämta en token för multifaktorautentisering.
Alias för användar-ID

: UID, användare		 UserID Ett strängvärde som instruerar klienten att utföra användarautentisering med det angivna användarnamnet.
Användarnamn för spårning TraceUserName Ett valfritt strängvärde som rapporterar till tjänsten vilket användarnamn som ska användas vid spårning av begäran internt.
Alias för användartoken

: UsrToken, UserToken		 UserToken Ett strängvärde som instruerar klienten att utföra användarautentisering med den angivna ägartoken.

Åsidosättningar ApplicationClientId, ApplicationKeyoch ApplicationToken. Om det anges hoppar det faktiska klientautentiseringsflödet till förmån för den angivna token.

Egenskapskombinationer som stöds för användarautentisering

För användarautentisering anger du AAD Federated Security som true. Välj sedan något av följande autentiseringslägen och ange relevanta egenskaper för det läget.

Autentiseringsläge Egenskapsnamn
Microsoft Entra användarfråga om autentisering – Användar-ID (valfritt)
– Utfärdar-ID (valfritt)
– Framtvinga MFA (valfritt)
– Användarnamn för spårning (valfritt)
Microsoft Entra användartokenautentisering – Användartoken
– Framtvinga MFA (valfritt)
– Användarnamn för spårning (valfritt)

Egenskaper för programautentisering

Egenskapsnamn Programmatiskt namn Description
federerad säkerhet

för Microsoft Entra-IDAlias: Federerad säkerhet, federerad, Fed, AADFed		 Federerad säkerhet Ett booleskt värde som instruerar klienten att utföra Microsoft Entra federerad ID-autentisering.
SendX5c-alias

för programcertifikat: Skicka offentligt certifikat för programcertifikat, SendX5c		 ApplicationCertificateSendX5c Ett booleskt värde som instruerar klienten att utföra ämnesnamn och utfärdarbaserad autentisering.
Tumavtrycksalias

för programcertifikat: AppCert		 ApplicationCertificateThumbprint Ett strängvärde som ger tumavtrycket för klientcertifikatet som ska användas när du använder ett flöde för autentisering av programklientcertifikat.
Alias för programklient-ID

: AppClientId		 ApplicationClientId Ett strängvärde som tillhandahåller det programklient-ID som ska användas vid autentisering.
Alias för programnyckel

: AppKey		 ApplicationKey Ett strängvärde som tillhandahåller programnyckeln som ska användas vid autentisering med hjälp av ett programhemlighetsflöde.
Programnamn för spårningsalias

: TraceAppName		 ApplicationNameForTracing Ett valfritt strängvärde som rapporterar till tjänsten vilket programnamn som ska användas när begäran spåras internt.
Alias för programtoken

: AppToken		 ApplicationToken Ett strängvärde som instruerar klienten att utföra programautentisering med angiven ägartoken.
Alias för utfärdar-ID

: TenantId		 Myndighet Ett strängvärde som anger namnet eller ID:t för den klientorganisation där programmet är registrerat. Standardvärdet är microsoft.com. Mer information finns i Microsoft Entra utfärdare.
Alias för Azure-region

: AzureRegion, Region		 AzureRegion Ett strängvärde som anger namnet på den Azure-region som du vill autentisera i.
ManagedServiceIdentity EmbeddedManagedIdentity Ett strängvärde som instruerar klienten vilken programidentitet som ska användas med autentisering av hanterad identitet. Använd system för att ange den systemtilldelade identiteten.

Den här egenskapen kan inte anges med en anslutningssträng, endast programmatiskt.
Alias för certifikatmottagare för unikt namn

: Certifikatmottagare för program		 ApplicationCertificateSubjectDistinguishedName Ett strängvärde som anger det unika namnet på programcertifikatets ämne.
Unikt namnalias

för programcertifikatutfärdare: Utfärdare av programcertifikat		 ApplicationCertificateIssuerDistinguishedName Ett strängvärde som anger det unika namnet på programcertifikatutfärdaren.

Egenskapskombinationer som stöds för programautentisering

För programautentisering anger du AAD Federated Security som true. Välj sedan något av följande autentiseringslägen och ange relevanta egenskaper för det läget.

Autentiseringsläge Egenskapsnamn
Microsoft Entra autentisering av programnyckel – Programklient-ID
– Programnyckel
– Utfärdar-ID
– Programnamn för spårning (valfritt)
Microsoft Entra Autentisering av tumavtryck för program – Programklient-ID
– Tumavtryck
för programcertifikat – Utfärdar-ID
– Programnamn för spårning (valfritt)
Microsoft Entra programämne och utfärdarautentisering – Programklient-ID
– Unikt namn
för certifikatmottagare för programcertifikatutfärdare – Utfärdarens unika namn
– Utfärdar-ID
– Azure-region (valfritt)
– Programcertifikat – SendX5c (valfritt)
– Programnamn för spårning (valfritt)
Microsoft Entra Autentisering av programämnesnamn – Programklient-ID
– Programcertifikatets unika namn
– Utfärdar-ID
och Azure-region (valfritt)
– Programnamn för spårning (valfritt)
Microsoft Entra autentisering av programtoken – Programtoken
– Programnamn för spårning (valfritt)

Autentisering med ett programcertifikat

  1. Programmet ska konfigureras för att acceptera det angivna certifikatet. Autentisering baserat på Microsoft Entra programcertifikat.
  2. Programmet ska konfigureras som ett auktoriserat huvudnamn i det relevanta Kusto-klustret.
  3. Certifikatet måste installeras i det lokala datorarkivet eller i det aktuella användararkivet.
  4. Certifikatets offentliga nyckel ska innehålla minst 2 048 bitar.

Egenskaper för klientkommunikation

Egenskapsnamn Programmatiskt namn Description
Acceptera Acceptera Ett booleskt värde som begär att detaljerade felobjekt returneras vid fel.
Strömning Strömning Ett booleskt värde som begär att klienten inte ackumulerar data innan den skickas till anroparen. Detta är standardbeteendet.
Okomprimerade Okomprimerade Ett booleskt värde som begär att klienten inte ber om komprimering på transportnivå.

Anteckning

Streaming När flaggan är aktiverad (som är standard) buffrar SDK inte alla svarsdata i minnet. I stället "hämtar" den data från tjänsten när anroparen begär det. Därför är det viktigt att anroparen i det här fallet tar bort data (till exempel IDataReader) när de är klara med att läsa data, eftersom nätverksanslutningen till tjänsten hålls öppen i onödan.

Exempel

Microsoft Entra-ID Federerad autentisering med den inloggade användaridentiteten (användaren tillfrågas om det behövs)

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 Federerad autentisering med tips om användar-ID (användaren tillfrågas om det behövs)

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 Federerad programautentisering med ApplicationClientId och 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}"

Använda systemtilldelad hanterad identitet

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadSystemManagedIdentity();

Använda användartilldelad hanterad identitet

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserManagedIdentity(managedIdentityClientId);

Microsoft Entra-ID federerad autentisering med hjälp av användar-/programtoken

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}"

Använda motringning för tokenprovider (anropas varje gång en token krävs)

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);

Använda X.509-certifikat

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);

Använda X.509-certifikat med tumavtryck (klienten försöker läsa in certifikatet från det lokala arkivet)

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}"