Stringhe di connessione Kusto

  • Articolo

Le stringhe di connessione Kusto forniscono le informazioni necessarie per un'applicazione client Kusto per stabilire una connessione a un endpoint del servizio Kusto. Le stringhe di connessione Kusto vengono modellate dopo le stringhe di connessione ADO.NET. Ovvero, il stringa di connessione è un elenco delimitato da punto e virgola di coppie di parametri nome-valore, preceduto facoltativamente da un singolo URI.

Ad esempio, il stringa di connessione Kusto seguente inizia con un URI che specifica l'endpoint del servizio per la comunicazione: . https://help.kusto.windows.net Questo URI viene assegnato alla Data Source proprietà . Successivamente, /Samples all'interno del stringa di connessione rappresenta il database predefinito e viene assegnato alla Initial Catalog proprietà . Infine, altre due proprietà Fed e Accept, forniscono altre opzioni di configurazione o personalizzazione per la connessione.

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

Nota

  • I nomi delle proprietà non fanno distinzione tra maiuscole e minuscole.
  • I valori delle proprietà fanno distinzione tra maiuscole e minuscole.
  • Gli spazi tra le coppie di parametri nome-valore vengono ignorati.
  • Un valore della proprietà che contiene un punto e virgola (;), una virgoletta singola (') o una virgoletta doppia (") deve essere racchiusa tra virgolette doppie.

Diversi strumenti client Kusto supportano un'estensione sul prefisso URI del stringa di connessione che consente un formato abbreviato di @ClusterName/InitialCatalog. Ad esempio, questi strumenti convertono il stringa di connessione @help/Samples in https://help.kusto.windows.net/Samples; Fed=true.

A livello di codice, la classe C# Kusto.Data.KustoConnectionStringBuilder può analizzare e modificare le stringhe di connessione Kusto. Questa classe convalida tutte le stringhe di connessione e genera un'eccezione di runtime se la convalida non riesce. Questa funzionalità è presente in tutte le versioni di Kusto SDK.

Endpoint attendibili

Una connessione con un endpoint Kusto può essere stabilita solo se tale endpoint è attendibile. Il client Kusto considera attendibili tutti gli endpoint la cui parte del nome host viene emessa dal servizio. Ad esempio, gli endpoint il cui nome host DNS termina con kusto.windows.net.

Per impostazione predefinita, il client non stabilisce connessioni ad altri endpoint. Per consentire le connessioni ad altri endpoint, usare la Kusto.Data.Common.KustoTrustedEndpoints classe per aggiungere endpoint all'elenco di endpoint attendibili. Usare SetOverridePolicy per eseguire l'override dei criteri predefiniti e AddTrustedHosts per aggiungere nuove voci ai criteri esistenti.

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

Proprietà delle stringhe di connessione

Le tabelle seguenti elencano tutte le possibili proprietà che possono essere incluse in un stringa di connessione Kusto. Le tabelle forniscono anche nomi di alias per ogni proprietà. Inoltre, le tabelle indicano i nomi programmatici associati a ogni proprietà, che rappresenta il nome della proprietà nell'oggetto Kusto.Data.KustoConnectionStringBuilder .

Proprietà generali

Nome proprietà Nome programmatico Descrizione
Versione client per la traccia TraceClientVersion Quando si traccia la versione del client, usare questa proprietà.
Alias dell'origine

dati: Addr, Address, Network Address, Server		 DataSource URI che specifica l'endpoint del servizio Kusto. Ad esempio: https://mycluster.kusto.windows.net.
Alias catalogo

iniziale: database		 InitialCatalog Nome del database da utilizzare per impostazione predefinita. Ad esempio: MyDatabase.
Alias coerenza query

: QueryConsistency		 QueryConsistency Impostare su strongconsistency o weakconsistency per determinare se la query deve essere sincronizzata con i metadati prima dell'esecuzione.

Proprietà di autenticazione utente

Nome proprietà Nome programmatico Descrizione
sicurezza federata

Microsoft Entra IDAlias: Sicurezza federata, Federated, Fed, AADFed		 FederatedSecurity Valore booleano che indica al client di eseguire Microsoft Entra'autenticazione.
Alias ID

autorità: TenantId		 Authority Valore stringa che fornisce il nome o l'ID del tenant dell'utente. Il valore predefinito è microsoft.com. Per altre informazioni, vedere autorità di Microsoft Entra.
Imponi alias MFA: MFA

, EnforceMFA		 EnforceMfa Valore booleano facoltativo che indica al client di acquisire un token di autenticazione a più fattori.
Alias ID

utente: UID, User		 UserID Valore stringa che indica al client di eseguire l'autenticazione utente con il nome utente indicato.
Nome utente per la traccia TraceUserName Valore stringa facoltativo che segnala al servizio il nome utente da usare durante la traccia interna della richiesta.
Alias del token

utente: UsrToken, UserToken		 UserToken Valore stringa che indica al client di eseguire l'autenticazione utente con il token di connessione specificato.

Esegue l'override ApplicationClientIddi , ApplicationKeye ApplicationToken. Se specificato, ignora il flusso di autenticazione client effettivo a favore del token fornito.

Combinazioni di proprietà supportate per l'autenticazione utente

Per l'autenticazione utente, specificare AAD Federated Security come true. Scegliere quindi una delle modalità di autenticazione seguenti e specificare le proprietà pertinenti per tale modalità.

Modalità di autenticazione Nomi delle proprietà
Microsoft Entra'autenticazione richiesta dell'utente - ID utente (facoltativo)
- ID autorità (facoltativo)
- Imponi MFA (facoltativo)
- Nome utente per la traccia (facoltativo)
autenticazione token utente Microsoft Entra - Token
utente- Imponi MFA (facoltativo)
- Nome utente per la traccia (facoltativo)

Proprietà di autenticazione dell'applicazione

Nome proprietà Nome programmatico Descrizione
sicurezza federata

Microsoft Entra IDAlias: Sicurezza federata, Federated, Fed, AADFed		 FederatedSecurity Valore booleano che indica al client di eseguire l'autenticazione federata Microsoft Entra ID.
Alias sendX5c

del certificato dell'applicazione: certificato applicazione invia certificato pubblico, SendX5c		 ApplicationCertificateSendX5c Valore booleano che indica al client di eseguire l'autenticazione basata sul nome soggetto e sull'autorità emittente.
Alias identificazione personale

del certificato dell'applicazione: AppCert		 ApplicationCertificateThumbprint Valore stringa che fornisce l'identificazione personale del certificato client da usare quando si usa un certificato client dell'applicazione che esegue l'autenticazione del flusso.
Alias ID

client dell'applicazione: AppClientId		 ApplicationClientId Valore stringa che fornisce l'ID client dell'applicazione da usare per l'autenticazione.
Alias chiave

applicazione: AppKey		 ApplicationKey Valore stringa che fornisce la chiave dell'applicazione da usare per l'autenticazione tramite un flusso del segreto dell'applicazione.
Nome applicazione per l'alias di traccia

: TraceAppName		 ApplicationNameForTracing Valore stringa facoltativo che segnala al servizio il nome dell'applicazione da usare durante la traccia interna della richiesta.
Alias del token

dell'applicazione: AppToken		 ApplicationToken Valore stringa che indica al client di eseguire l'autenticazione dell'applicazione con il token di connessione specificato.
Alias ID

autorità: TenantId		 Authority Valore stringa che fornisce il nome o l'ID del tenant in cui è registrata l'applicazione. Il valore predefinito è microsoft.com. Per altre informazioni, vedere autorità di Microsoft Entra.
Alias dell'area di

Azure: AzureRegion, Area		 AzureRegion Valore stringa che fornisce il nome dell'area di Azure in cui eseguire l'autenticazione.
ManagedServiceIdentity EmbeddedManagedIdentity Valore stringa che indica al client quale identità dell'applicazione usare con l'autenticazione dell'identità gestita. Usare system per indicare l'identità assegnata dal sistema.

Questa proprietà non può essere impostata con un stringa di connessione, solo a livello di codice.
Alias del nome

distinto del soggetto del certificato dell'applicazione: soggetto certificato applicazione		 ApplicationCertificateSubjectDistinguishedName Valore stringa che specifica il nome distinto dell'oggetto del certificato dell'applicazione.
Alias del nome

distinto dell'autorità di certificazione dell'applicazione: autorità di certificazione dell'applicazione		 ApplicationCertificateIssuerDistinguishedName Valore stringa che specifica il nome distinto dell'autorità di certificazione dell'applicazione.

Combinazioni di proprietà supportate per l'autenticazione dell'applicazione

Per l'autenticazione dell'applicazione, specificare AAD Federated Security come true. Scegliere quindi una delle modalità di autenticazione seguenti e specificare le proprietà pertinenti per tale modalità.

Modalità di autenticazione Nomi delle proprietà
Microsoft Entra autenticazione della chiave dell'applicazione - ID
client applicazione- Chiave
applicazione- ID
autorità - Nome applicazione per la traccia (facoltativo)
autenticazione dell'identificazione personale dell'applicazione Microsoft Entra - ID
client dell'applicazione - Identificazione
personale del certificato dell'applicazione - ID
autorità - Nome applicazione per la traccia (facoltativo)
Microsoft Entra l'oggetto dell'applicazione e l'autenticazione dell'autorità emittente - ID
client dell'applicazione- Nome
distinto del soggetto del certificato applicazione - Nome distinto
dell'autorità di certificazione - ID
autorità - Area di Azure (facoltativo)
- Invio certificato applicazione (facoltativo)
- Nome applicazione per la traccia (facoltativo)
autenticazione del nome soggetto dell'applicazione Microsoft Entra - ID
client applicazione- Nome
distinto soggetto certificato applicazione - ID
autorità - Area di Azure (facoltativo)
- Nome applicazione per la traccia (facoltativo)
autenticazione del token di applicazione Microsoft Entra - Token
applicazione - Nome applicazione per la traccia (facoltativo)

Autenticazione con un certificato dell'applicazione

  1. L'applicazione deve essere configurata per accettare il certificato specificato. Come eseguire l'autenticazione basata sul certificato dell'applicazione di Microsoft Entra.
  2. L'applicazione deve essere configurata come entità autorizzata nel cluster Kusto pertinente.
  3. Il certificato deve essere installato nell'archivio computer locale o nell'archivio utente corrente.
  4. La chiave pubblica del certificato deve contenere almeno 2048 bit.

Proprietà di comunicazione client

Nome proprietà Nome programmatico Descrizione
Accetta Accetta Valore booleano che richiede la restituzione di oggetti errore dettagliati in caso di errore.
Streaming Streaming Valore booleano che richiede al client di non accumulare dati prima di fornirli al chiamante. Si tratta di un comportamento predefinito.
Non compresso Non compresso Valore booleano che richiede al client di non richiedere la compressione a livello di trasporto.

Nota

Quando il Streaming flag è abilitato (come è l'impostazione predefinita), l'SDK non memorizza nel buffer tutti i dati di risposta in memoria, ma esegue il pull dei dati dal servizio quando il chiamante lo richiede. Pertanto, è essenziale che in questo caso il chiamante elimini correttamente i dati (ad esempio IDataReader) una volta eseguiti la lettura dei dati, perché la connessione di rete al servizio viene mantenuta aperta inutilmente.

Esempio

Microsoft Entra'autenticazione federata con ID con l'identità utente attualmente connessa (se necessario verrà richiesto l'utente)

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 Autenticazione federata con ID utente (se necessario verrà richiesto l'utente)

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'autenticazione dell'applicazione federata con ID applicazione con ApplicationClientId e 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}"

Uso dell'identità gestita assegnata dal sistema

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

Uso dell'identità gestita assegnata dall'utente

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

Microsoft Entra'autenticazione federata con ID utente/token dell'applicazione

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

Uso del callback del provider di token (verrà richiamato ogni volta che è necessario un token)

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

Uso del certificato X.509

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

Uso del certificato X.509 tramite identificazione personale (il client tenterà di caricare il certificato dall'archivio locale)

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