Cadeias de conexão Kusto

Selecione um serviço na lista suspensa à esquerda.
Aplica-se a: ✅ Microsoft Fabric ✅ Azure Data Explorer

As cadeias de conexão Kusto fornecem as informações necessárias para que um aplicativo cliente Kusto estabeleça uma conexão com um ponto de extremidade de serviço Kusto. As cadeias de conexão Kusto são modeladas de acordo com as cadeias de conexão ADO.NET. Ou seja, a cadeia de conexão é uma lista delimitada por ponto-e-vírgula de pares de parâmetros nome-valor, opcionalmente prefixada por um único URI.

Por exemplo, a seguinte cadeia de conexão Kusto começa com um URI que especifica o ponto de extremidade de serviço para comunicação: https://help.kusto.windows.net. Esse URI é atribuído à propriedade Data Source. Em seguida, /Samples dentro da cadeia de conexão representa o banco de dados padrão e é atribuído à propriedade Initial Catalog. Por fim, duas outras propriedades, Fed e Accept, fornecem mais opções de configuração ou personalização para a conexão.

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

Observação

• Os nomes de propriedade não diferenciam maiúsculas de minúsculas.
• Os valores de propriedade diferenciam maiúsculas de minúsculas.
• Os espaços entre pares de parâmetros nome-valor são ignorados.
• Um valor de propriedade que contenha um ponto-e-vírgula (;), aspas simples (') ou aspas duplas (") deve ser colocado entre aspas duplas.

Programaticamente, a classe C# Kusto.Data.KustoConnectionStringBuilder pode analisar e manipular cadeias de conexão Kusto. Essa classe valida todas as cadeias de conexão e gera uma exceção de tempo de execução se a validação falhar. Esta funcionalidade está presente em todos os sabores do Kusto SDK.

Pontos de extremidade confiáveis

Uma conexão com um ponto de extremidade Kusto só pode ser estabelecida se esse ponto de extremidade for confiável. O cliente Kusto confia em todos os pontos de extremidade cujo domínio de host é emitido pelo serviço. Por exemplo, pontos de extremidade cujo nome de host DNS termina com kusto.windows.net.

Por padrão, o cliente não estabelece conexões com outros pontos de extremidade. Para permitir conexões com outros pontos de extremidade, use a classe Kusto.Data.Common.KustoTrustedEndpoints para adicionar pontos de extremidade à lista de pontos de extremidade confiáveis. Use SetOverridePolicy para substituir a política padrão e AddTrustedHosts para adicionar novas entradas à política existente.

KustoTrustedEndpoints.AddTrustedHosts(
    new[]
    {
        // Allow an explicit service address
        new FastSuffixMatcher<EndpointContext>.MatchRule("my-kusto.contoso.com", exact: true, new EndpointContext(EndpointType.Kusto)),
        // Allow services whose DNS name end with ".contoso.com"
        new FastSuffixMatcher<EndpointContext>.MatchRule(".contoso.com", exact: false, new EndpointContext(EndpointType.Kusto)),
    }
);

Para mais informações sobre como contornar redes restritas, consulte Gerir restrições de rede de clientes.

Propriedades da cadeia de conexão

As tabelas a seguir listam todas as propriedades possíveis que podem ser incluídas em uma cadeia de conexão Kusto e fornecem nomes de alias para cada propriedade. Além disso, as tabelas observam o nome programático associado a cada propriedade, que representa o nome da propriedade no objeto Kusto.Data.KustoConnectionStringBuilder.

Propriedades gerais

Nome da propriedade	Nome programático	Descrição
Versão do cliente para rastreamento	TraceClientVersion	A propriedade usada ao rastrear a versão do cliente.
Fonte de dados aliases: Addr, Endereço, Endereço de rede, Servidor	Fonte de dados	O URI especificando o ponto de extremidade do serviço Kusto. Por exemplo, https://mycluster.kusto.windows.net.
Catálogo inicial alias: banco de dados	Catálogo Inicial	O nome do banco de dados padrão. Por exemplo, MyDatabase.
Consistência da consulta Alias: QueryConsistency	QueryConsistency	Defina como strongconsistency ou weakconsistency para determinar se a consulta deve ser sincronizada com os metadados antes da execução.

Propriedades de autenticação do usuário

Nome da propriedade	Nome programático	Descrição
Aliases do de Segurança Federada do Microsoft Entra ID: Federated Security, Federated, Fed, AADFed	Segurança Federada	Um valor booleano que instrui o cliente a executar a autenticação do Microsoft Entra.
ID da autoridade alias: TenantId	Autoridade	Um valor de cadeia de caracteres que fornece o nome ou ID do locatário do usuário. O valor padrão é microsoft.com. Para obter mais informações, consulte Microsoft Entra authority.
ID de usuário aliases: UID, Usuário	ID de utilizador	Um valor de cadeia de caracteres que instrui o cliente a executar a autenticação do usuário com o nome de usuário indicado.
Nome de usuário para rastreamento	TraceUserName	Um valor de cadeia de caracteres opcional que informa ao serviço qual nome de usuário usar ao rastrear a solicitação internamente.
Token de usuário aliases: UsrToken, UserToken	Token de usuário	Um valor de cadeia de caracteres que instrui o cliente a executar a autenticação do usuário com o token de portador especificado. Substitui ApplicationClientId, ApplicationKeye ApplicationToken. Se especificado, ignora o fluxo de autenticação do cliente real em favor do token fornecido.

Combinações de propriedades suportadas para autenticação de usuário

Para autenticação de usuário, especifique AAD Federated Security como true. Em seguida, escolha um dos seguintes modos de autenticação e especifique as propriedades relevantes para esse modo.

Modo de autenticação	Nomes de propriedade
Autenticação de prompt de usuário do Microsoft Entra	- ID de usuário (opcional) - ID da autoridade (opcional) - Nome de usuário para rastreamento (opcional)
Autenticação de Token de usuário do Microsoft Entra	- User Token - Nome de usuário para rastreamento (opcional)

Propriedades de autenticação de aplicativos

Nome da propriedade	Nome programático	Descrição
Aliases do de Segurança Federada do Microsoft Entra ID: Federated Security, Federated, Fed, AADFed	Segurança Federada	Um valor booleano que instrui o cliente a executar a autenticação federada do Microsoft Entra ID.
Certificado de Aplicação SendX5c Aliases: Certificado de Aplicação Enviar Certificado Público, SendX5c	ApplicationCertificateSendX5c	Um valor booleano que instrui o cliente a executar o nome do assunto e a autenticação baseada no emissor.
Impressão digital do certificado de aplicativo Alias: AppCert	ApplicationCertificateImpressão digital	Um valor de cadeia de caracteres que fornece a impressão digital do certificado do cliente a ser usado ao usar um fluxo de autenticação de certificado de cliente de aplicativo.
ID do cliente do aplicativo alias: AppClientId	ApplicationClientId	Um valor de cadeia de caracteres que fornece a ID do cliente do aplicativo a ser usada durante a autenticação.
Chave de aplicativo alias: AppKey	Chave de Aplicação	Um valor de cadeia de caracteres que fornece a chave do aplicativo a ser usada ao autenticar usando um fluxo secreto do aplicativo.
Nome do aplicativo para rastreamento alias: TraceAppName	ApplicationNameForTracing	Um valor de cadeia de caracteres opcional que relata ao serviço qual nome de aplicativo usar ao rastrear a solicitação internamente.
Token de aplicativo Alias: AppToken	ApplicationToken	Um valor de cadeia de caracteres que instrui o cliente a executar a autenticação do aplicativo com o token de portador especificado.
ID da autoridade alias: TenantId	Autoridade	Um valor de cadeia de caracteres que fornece o nome ou ID do locatário no qual o aplicativo está registrado. O valor padrão é microsoft.com. Para obter mais informações, consulte Microsoft Entra authority.
Aliases de da Região do Azure: AzureRegion, Region	AzureRegião	Um valor de cadeia de caracteres que fornece o nome da Região do Azure na qual autenticar.
ManagedServiceIdentity	EmbeddedManagedIdentity	Um valor de cadeia de caracteres que instrui o cliente qual identidade de aplicativo usar com a autenticação de identidade gerenciada. Use system para indicar a identidade atribuída ao sistema. Esta propriedade não pode ser definida com uma cadeia de conexão, apenas programaticamente.
Nome distinto alias da entidade do certificado de aplicativo: Assunto do certificado de aplicativo	ApplicationCertificateSubjectDistinguishedName	Um valor de cadeia de caracteres que especifica o nome distinto da entidade do certificado do aplicativo.
Nome distinto alias do emissor do certificado de aplicativo: emissor do certificado de aplicativo	ApplicationCertificateIssuerDistinguishedName	Um valor de cadeia de caracteres que especifica o nome distinto do emissor do certificado do aplicativo.

Combinações de propriedades suportadas para autenticação de aplicativos

Para autenticação de aplicativos, especifique AAD Federated Security como true. Em seguida, escolha um dos seguintes modos de autenticação e especifique as propriedades relevantes para esse modo.

Modo de autenticação	Nomes de propriedade
Autenticação de chave de aplicativo Microsoft Entra	- ID do cliente do aplicativo - Chave de Aplicação - Identificação da autoridade - Nome do aplicativo para rastreamento (opcional)
Autenticação de impressão digital do aplicativo Microsoft Entra	- Identificação do Cliente de Aplicação - Impressão digital do certificado de aplicação - Identificação da autoridade - Nome do aplicativo para rastreamento (opcional)
Assunto do aplicativo Microsoft Entra e autenticação do emissor	- ID do Cliente do Aplicativo - Nome Distinto do Assunto do Certificado de Aplicação - Nome Distinto do Emissor do Certificado de Aplicação - Id da Autoridade - Região do Azure (opcional) - Certificado de Aplicação SendX5c (opcional) - Nome do aplicativo para rastreamento (opcional)
Autenticação de Nome do Assunto do Aplicativo Microsoft Entra	- ID do Cliente do Aplicativo - Nome Distinto do Assunto do Certificado de Aplicação - ID da Autoridade - e Região do Azure (opcional) - Nome do aplicativo para rastreamento (opcional)
Autenticação de Token de Aplicativo Microsoft Entra	- Application Token - Nome do aplicativo para rastreamento (opcional)

Autenticação com um certificado de aplicativo

1. O aplicativo deve ser configurado para aceitar o certificado fornecido. Como autenticar com base no certificado do aplicativo Microsoft Entra.
2. O aplicativo deve ser configurado como uma entidade autorizada no ambiente Kusto relevante.
3. O certificado precisa ser instalado no armazenamento do Computador Local ou no repositório do Usuário Atual.
4. A chave pública do certificado deve conter pelo menos 2.048 bits.

Propriedades de comunicação com o cliente

Nome da propriedade	Nome programático	Descrição
Aceitar	Aceitar	Um valor booleano que solicita que objetos de erro detalhados sejam retornados em caso de falha.
Transmissão	Transmissão	Um valor booleano que solicita que o cliente forneça dados imediatamente ao chamador sem acumulá-los primeiro. O streaming é um comportamento padrão.
Sem compressão	Sem compressão	Um valor booleano que instrui o cliente a evitar solicitar compactação no nível de transporte.

Observação

Quando o sinalizador Streaming está ativado (padrão), o SDK não armazena em buffer todos os dados de resposta na memória; em vez disso, ele "extrai" os dados do serviço quando o chamador os solicita. Neste caso, o chamador deve descartar corretamente os dados, como IDataReader, uma vez que é feita a leitura dos dados, pois a conexão de rede com o serviço é mantida aberta desnecessariamente.

Exemplos

Os exemplos a seguir mostram como configurar conexões usando C#. Para obter exemplos em outros idiomas, consulte Métodos de autenticação de aplicativos.

Autenticação federada do Microsoft Entra ID com identidade de usuário atual

O exemplo a seguir mostra como configurar uma conexão com um serviço Kusto usando o Microsoft Entra ID para autenticação federada. O usuário é solicitado a fornecer credenciais, quando necessário.

using Kusto.Data;

var kustoUri = "serviceURI";
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}"

Autenticação federada do Microsoft Entra ID com dica de ID do usuário

O exemplo a seguir mostra como configurar uma conexão com um serviço Kusto usando o Microsoft Entra ID para autenticação federada e pré-preenche a identidade do usuário usando a variável userID. O usuário é solicitado a fornecer credenciais, quando necessário.

using Kusto.Data;

var kustoUri = "serviceURI";
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}"

Autenticação de aplicativo federado Microsoft Entra ID com ApplicationClientId e ApplicationKey

O exemplo a seguir mostra como autenticar em um serviço Kusto usando o Microsoft Entra ID para autenticação federada com uma ID e chave de cliente de aplicativo.

using Kusto.Data;

var kustoUri = "serviceURI";
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}"

Autenticação federada do Microsoft Entra ID com tokens de usuário e aplicativo

O exemplo a seguir mostra como configurar uma conexão com um serviço Kusto usando o Microsoft Entra ID com um token de acesso de usuário ou um token de acesso de aplicativo.

using Kusto.Data;

var kustoUri = "serviceURI";
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}"

Autenticação com retorno de chamada do provedor de token

O exemplo a seguir mostra como autenticar em um serviço Kusto usando o Microsoft Entra ID com um retorno de chamada de provedor de token personalizado. O token é invocado sempre que um token é necessário.

using Kusto.Data;

var kustoUri = "serviceURI";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

Autenticação com certificado X.509

O exemplo a seguir mostra como autenticar em um serviço Kusto usando o Microsoft Entra ID para autenticação federada com um certificado de aplicativo.

using Kusto.Data;

var kustoUri = "serviceURI";
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);

Autenticação com impressão digital de certificado X.509

O exemplo a seguir mostra como configurar uma conexão com um serviço Kusto usando o Microsoft Entra ID com uma impressão digital de certificado de aplicativo. O cliente tenta carregar o certificado de um armazenamento local.

using Kusto.Data;

var kustoUri = "serviceURI";
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}"

Conteúdo relacionado

• Visão geral das cadeias de conexão
• Kusto API
• Linguagem de consulta Kusto (KQL)