Kusto-verbindingsreeksen

  • Artikel

Kusto-verbindingsreeksen bieden de informatie die een Kusto-clienttoepassing nodig heeft om een verbinding met een Kusto-service-eindpunt tot stand te brengen. Kusto-verbindingsreeksen worden gemodelleerd naar de ADO.NET verbindingsreeksen. Dat wil gezegd, de verbindingsreeks is een door puntkomma's gescheiden lijst met parameterparen voor naam en waarde, optioneel voorafgegaan door één URI.

De volgende Kusto-verbindingsreeks begint bijvoorbeeld met een URI die het service-eindpunt voor communicatie specificeert: https://help.kusto.windows.net. Deze URI wordt toegewezen aan de Data Source eigenschap. /Samples Vervolgens vertegenwoordigt binnen de verbindingsreeks de standaarddatabase en wordt toegewezen aan de Initial Catalog eigenschap. Ten slotte bieden twee andere eigenschappen, Fed en Accept, verdere configuratie- of aanpassingsopties voor de verbinding.

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

Notitie

  • Eigenschapsnamen zijn niet hoofdlettergevoelig.
  • Eigenschapswaarden zijn hoofdlettergevoelig.
  • Spaties tussen parameterparen voor naam en waarde worden genegeerd.
  • Een eigenschapswaarde die een puntkomma (;), een enkel aanhalingsteken (') of een dubbel aanhalingsteken (") bevat, moet tussen dubbele aanhalingstekens staan.

Verschillende Kusto-clienthulpprogramma's ondersteunen een extensie via het URI-voorvoegsel van de verbindingsreeks die een verkorte indeling van @ClusterName/InitialCatalog mogelijk maakt. Met deze hulpprogramma's wordt de verbindingsreeks @help/Samples bijvoorbeeld omgezet in https://help.kusto.windows.net/Samples; Fed=true.

Programmatisch kan de C# Kusto.Data.KustoConnectionStringBuilder -klasse Kusto-verbindingsreeksen parseren en bewerken. Deze klasse valideert alle verbindingsreeksen en genereert een runtime-uitzondering als de validatie mislukt. Deze functionaliteit is aanwezig in alle varianten van de Kusto SDK.

Vertrouwde eindpunten

Een verbinding met een Kusto-eindpunt kan alleen tot stand worden gebracht als dat eindpunt wordt vertrouwd. De Kusto-client vertrouwt alle eindpunten waarvan het hostnaamonderdeel wordt uitgegeven door de service. Bijvoorbeeld eindpunten waarvan de DNS-hostnaam eindigt op kusto.windows.net.

Standaard maakt de client geen verbindingen met andere eindpunten. Als u verbindingen met andere eindpunten wilt toestaan, gebruikt u de Kusto.Data.Common.KustoTrustedEndpoints klasse om eindpunten toe te voegen aan de lijst met vertrouwde eindpunten. Gebruik SetOverridePolicy om het standaardbeleid te overschrijven en AddTrustedHosts om nieuwe vermeldingen toe te voegen aan het bestaande beleid.

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

Eigenschappen voor de verbindingsreeks

De volgende tabellen bevatten alle mogelijke eigenschappen die kunnen worden opgenomen in een Kusto-verbindingsreeks. De tabellen bevatten ook aliasnamen voor elke eigenschap. Bovendien geven de tabellen de programmatische namen aan die aan elke eigenschap zijn gekoppeld, die de naam van de eigenschap in het Kusto.Data.KustoConnectionStringBuilder object vertegenwoordigen.

Algemene eigenschappen

Naam van eigenschap Programmatische naam Description
Clientversie voor tracering TraceClientVersion Gebruik deze eigenschap bij het traceren van de clientversie.
Gegevensbronaliassen

: Addr, Address, Network Address, Server		 Datasource De URI die het Kusto-service-eindpunt opgeeft. Bijvoorbeeld https://mycluster.kusto.windows.net.
Initiëlecatalogusalias

: Database		 InitialCatalog De naam van de database die standaard moet worden gebruikt. Bijvoorbeeld MyDatabase.
Queryconsistentiealias

: QueryConsistentie		 QueryConsistentie Stel in op strongconsistency of weakconsistency om te bepalen of de query moet worden gesynchroniseerd met de metagegevens voordat deze wordt uitgevoerd.

Eigenschappen van gebruikersverificatie

Naam van eigenschap Programmatische naam Description
federatieve beveiliging

van Microsoft Entra-idAliassen: Federatieve beveiliging, Federatief, Fed, AADFed		 Federatieve beveiliging Een booleaanse waarde die de client instrueert om Microsoft Entra verificatie uit te voeren.
Instantie-id-alias

: TenantId		 Instantie Een tekenreekswaarde die de naam of id van de tenant van de gebruiker aangeeft. De standaardwaarde is microsoft.com. Zie Microsoft Entra instantie voor meer informatie.
MFA-alias

afdwingen: MFA, AfdwingenMFA		 EnforceMfa Een optionele Booleaanse waarde waarmee de client wordt geïnstrueerd om een token voor meervoudige verificatie te verkrijgen.
Gebruikers-id-aliassen

: UID, Gebruiker		 UserID Een tekenreekswaarde die de client instrueert om gebruikersverificatie uit te voeren met de aangegeven gebruikersnaam.
Gebruikersnaam voor tracering TraceUserName Een optionele tekenreekswaarde die aan de service rapporteert welke gebruikersnaam moet worden gebruikt bij het intern traceren van de aanvraag.
Gebruikerstokenaliassen

: UsrToken, UserToken		 UserToken Een tekenreekswaarde die de client instrueert om gebruikersverificatie uit te voeren met het opgegeven bearer-token.

Overschrijft ApplicationClientId, ApplicationKeyen ApplicationToken. Indien opgegeven, wordt de werkelijke clientverificatiestroom overgeslagen ten gunste van het opgegeven token.

Ondersteunde eigenschappencombinaties voor gebruikersverificatie

Geef voor gebruikersverificatie op AAD Federated Security als true. Kies vervolgens een van de volgende verificatiemodi en geef de relevante eigenschappen voor die modus op.

Verificatiemodus Eigenschapsnamen
Microsoft Entra gebruikerspromptverificatie - Gebruikers-id (optioneel)
- Instantie-id (optioneel)
- MFA afdwingen (optioneel)
- Gebruikersnaam voor tracering (optioneel)
tokenverificatie voor Microsoft Entra gebruiker - Gebruikerstoken
- MFA afdwingen (optioneel)
- Gebruikersnaam voor tracering (optioneel)

Eigenschappen van toepassingsverificatie

Naam van eigenschap Programmatische naam Description
federatieve beveiliging

van Microsoft Entra-idAliassen: Federatieve beveiliging, Federatief, Fed, AADFed		 Federatieve beveiliging Een Booleaanse waarde die de client instrueert om Microsoft Entra id federatieve verificatie uit te voeren.
SendX5c-aliassen

van toepassingscertificaat: Toepassingscertificaat openbaar certificaat verzenden, SendX5c		 ApplicationCertificateSendX5c Een booleaanse waarde die de client instrueert om verificatie op basis van onderwerpnaam en verlener uit te voeren.
Alias voor vingerafdruk

van toepassingscertificaat: AppCert		 ApplicationCertificateThumbprint Een tekenreekswaarde die de vingerafdruk levert van het clientcertificaat dat moet worden gebruikt bij het gebruik van een verificatiestroom voor clientcertificaten van een toepassing.
Alias van toepassingsclient-id

: AppClientId		 ApplicationClientId Een tekenreekswaarde die de client-id van de toepassing aangeeft die moet worden gebruikt bij de verificatie.
Alias van toepassingssleutel

: AppKey		 ApplicationKey Een tekenreekswaarde die de toepassingssleutel levert die moet worden gebruikt bij verificatie met behulp van een stroom voor toepassingsgeheimen.
Toepassingsnaam voor traceringsalias

: TraceAppName		 ApplicationNameForTracing Een optionele tekenreekswaarde die aan de service rapporteert welke toepassingsnaam moet worden gebruikt bij het intern traceren van de aanvraag.
Alias van toepassingstoken

: AppToken		 ApplicationToken Een tekenreekswaarde die de client instrueert om toepassingsauthentificatie uit te voeren met het opgegeven bearer-token.
Instantie-id-alias

: TenantId		 Instantie Een tekenreekswaarde die de naam of id aangeeft van de tenant waarin de toepassing is geregistreerd. De standaardwaarde is microsoft.com. Zie Microsoft Entra instantie voor meer informatie.
Azure-regioaliassen

: AzureRegio, Regio		 AzureRegion Een tekenreekswaarde die de naam aangeeft van de Azure-regio waarin moet worden geverifieerd.
ManagedServiceIdentity EmbeddedManagedIdentity Een tekenreekswaarde die de client instrueert welke toepassingsidentiteit moet worden gebruikt met verificatie van beheerde identiteit. Gebruik system om de door het systeem toegewezen identiteit aan te geven.

Deze eigenschap kan niet worden ingesteld met een verbindingsreeks, alleen via een programma.
Alias voor DN-naam

van toepassingscertificaatonderwerp: Onderwerp van toepassingscertificaat		 ApplicationCertificateSubjectDistinguishedName Een tekenreekswaarde die de DN-naam van het toepassingscertificaat aangeeft.
Alias voor DN-naam

van verlener van toepassingscertificaat: Verlener van toepassingscertificaat		 ApplicationCertificateIssuerDistinguishedName Een tekenreekswaarde die de DN-naam van de verlener van het toepassingscertificaat aangeeft.

Ondersteunde eigenschapscombinaties voor toepassingsverificatie

Geef voor toepassingsverificatie op AAD Federated Security als true. Kies vervolgens een van de volgende verificatiemodi en geef de relevante eigenschappen voor die modus op.

Verificatiemodus Eigenschapsnamen
verificatie van de toepassingssleutel Microsoft Entra - Client-id
van toepassing - Toepassingssleutel
- Instantie-id
- Toepassingsnaam voor tracering (optioneel)
verificatie van vingerafdruk van Microsoft Entra-toepassing - Client-id
van toepassing - Vingerafdruk
van toepassingscertificaat - instantie-id
- toepassingsnaam voor tracering (optioneel)
verificatie van onderwerp en verlener van Microsoft Entra-toepassing - Client-id
van toepassing- DN-naam
van toepassingscertificaatonderwerp- DN-naam
van verlener van toepassingscertificaat - Instantie-id
- Azure-regio (optioneel)
- Toepassingscertificaat SendX5c (optioneel)
- Toepassingsnaam voor tracering (optioneel)
verificatie van onderwerpnaam van Microsoft Entra toepassing - Client-id
van toepassing- DN-naam
van toepassingscertificaatonderwerp- instantie-id
- en Azure-regio (optioneel)
- Toepassingsnaam voor tracering (optioneel)
verificatie van token voor Microsoft Entra-toepassing - Toepassingstoken
- Toepassingsnaam voor tracering (optioneel)

Verificatie met een toepassingscertificaat

  1. De toepassing moet worden geconfigureerd om het opgegeven certificaat te accepteren. Verificatie op basis van het certificaat van Microsoft Entra toepassing.
  2. De toepassing moet worden geconfigureerd als een geautoriseerde principal in het relevante Kusto-cluster.
  3. Het certificaat moet worden geïnstalleerd in het lokale computerarchief of in het archief van de huidige gebruiker.
  4. De openbare sleutel van het certificaat moet ten minste 2048 bits bevatten.

Eigenschappen van clientcommunicatie

Naam van eigenschap Programmatische naam Description
Accepteren Accepteren Een booleaanse waarde die vraagt om gedetailleerde foutobjecten die moeten worden geretourneerd bij een fout.
Streaming Streaming Een booleaanse waarde die aan de client vraagt om geen gegevens te verzamelen voordat deze aan de aanroeper worden verstrekt. Dit is standaardgedrag.
Ongecomprimeerde Ongecomprimeerde Een booleaanse waarde die de client vraagt om geen compressie op transportniveau.

Notitie

Wanneer de Streaming vlag is ingeschakeld (zoals de standaardinstelling is), buffert de SDK niet alle antwoordgegevens in het geheugen; in plaats daarvan worden de gegevens uit de service opgehaald wanneer de aanroeper daarom vraagt. Daarom is het essentieel dat in dit geval de aanroeper de gegevens correct verwijdert (zoals IDataReader) zodra de gegevens zijn gelezen, omdat de netwerkverbinding met de service onnodig wordt geopend.

Voorbeelden

Microsoft Entra id federatieve verificatie met behulp van de momenteel aangemelde gebruikersidentiteit (de gebruiker wordt hierom gevraagd indien nodig)

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 federatieve verificatie met hint voor gebruikers-id (de gebruiker wordt hierom gevraagd indien nodig)

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 federatieve toepassingsverificatie met ApplicationClientId en 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}"

Door het systeem toegewezen beheerde identiteit gebruiken

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

Door de gebruiker toegewezen beheerde identiteit gebruiken

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

Microsoft Entra-id federatieve verificatie met behulp van gebruiker/toepassingstoken

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

Callback van tokenprovider gebruiken (wordt telkens aangeroepen wanneer een token vereist is)

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

X.509-certificaat gebruiken

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

X.509-certificaat gebruiken via vingerafdruk (client probeert het certificaat uit het lokale archief te 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}"