Cadeias de conexão do Kusto
As cadeias de conexão do 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 do Kusto são modeladas de acordo com as cadeias de conexão do ADO.NET. Ou seja, o cadeia de conexão é uma lista delimitada por ponto e vírgula de pares de parâmetros nome-valor, opcionalmente prefixado por um único URI.
Por exemplo, o seguinte cadeia de conexão do 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 à Data Source propriedade . Em seguida, /Samples no cadeia de conexão representa o banco de dados padrão e é atribuído à Initial Catalog propriedade . 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.
- Espaços entre pares de parâmetros nome-valor são ignorados.
- Um valor de propriedade que contém um ponto e vírgula (
;), aspas simples (') ou aspas duplas (") devem estar entre aspas duplas.
Várias ferramentas de cliente Kusto dão suporte a uma extensão sobre o prefixo de URI do cadeia de conexão que permite um formato abreviado de @ClusterName/InitialCatalog. Por exemplo, essas ferramentas convertem o cadeia de conexão @help/Samples para https://help.kusto.windows.net/Samples; Fed=true.
Programaticamente, a classe C# Kusto.Data.KustoConnectionStringBuilder pode analisar e manipular cadeias de conexão kusto. Essa classe vai validar todas as cadeias de conexão e gerar uma exceção de runtime se a validação falhar. Essa funcionalidade está presente em todos os tipos de SDK do Kusto.
Pontos de extremidade confiáveis
Uma conexão com um ponto de extremidade kusto só poderá ser estabelecida se esse ponto de extremidade for confiável.
O cliente Kusto confia em todos os pontos de extremidade cuja parte do nome do host é emitida 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 Kusto.Data.Common.KustoTrustedEndpoints classe 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.MatchRule("my-kusto.contoso.com", exact: true),
// Allow services whose DNS name end with ".contoso.com"
new FastSuffixMatcher.MatchRule(".contoso.com", exact: false),
}
);
Propriedades de cadeia de conexão
As tabelas a seguir listam todas as propriedades possíveis que podem ser incluídas em um cadeia de conexão do Kusto. As tabelas também fornecem nomes de alias para cada propriedade. Além disso, as tabelas indicam os nomes programáticos associados a cada propriedade, que representa o nome da propriedade no Kusto.Data.KustoConnectionStringBuilder objeto .
Propriedades gerais
| Nome da propriedade | Nome programático | Descrição |
|---|---|---|
| Versão do cliente para rastreamento | TraceClientVersion | Ao rastrear a versão do cliente, use essa propriedade. |
| Aliases da fonte de dados: Addr, Address, Network Address, Server |
DataSource | O URI que especifica o ponto de extremidade de serviço do Kusto. Por exemplo, https://mycluster.kusto.windows.net. |
| Alias inicial do catálogo : banco de dados |
InitialCatalog | O nome do banco de dados a ser usado por padrão. Por exemplo, MyDatabase. |
| Alias de consistência de consulta: QueryConsistency |
QueryConsistency | Defina como strongconsistency ou weakconsistency para determinar se a consulta deve ser sincronizada com os metadados antes de ser executada. |
Propriedades de autenticação do usuário
| Nome da propriedade | Nome programático | Descrição |
|---|---|---|
| segurança federada da ID de Microsoft EntraAliases: Segurança Federada, Federada, Fed, AADFed |
FederatedSecurity | Um valor booliano que instrui o cliente a executar Microsoft Entra autenticação. |
| Alias de ID de autoridade: TenantId |
Authority | Um valor de cadeia de caracteres que fornece o nome ou a ID do locatário do usuário. O valor padrão é microsoft.com. Para obter mais informações, consulte Microsoft Entra autoridade. |
| Impor alias de MFA : MFA, EnforceMFA |
EnforceMfa | Um valor booliano opcional que instrui o cliente a adquirir um token de autenticação multifator. |
| Aliases de ID de Usuário: UID, Usuário |
UserID | 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 relata ao serviço qual nome de usuário usar ao rastrear a solicitação internamente. |
| Aliases de token de usuário: UsrToken, UserToken |
UserToken | Um valor de cadeia de caracteres que instrui o cliente a executar a autenticação do usuário com o token de portador especificado. ApplicationClientIdSubstitui , ApplicationKeye ApplicationToken. Se especificado, ignora o fluxo de autenticação de cliente real em favor do token fornecido. |
Combinações de propriedades com suporte 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 |
|---|---|
| Microsoft Entra autenticação de prompt de usuário | - ID de usuário (opcional) - ID de autoridade (opcional) - Impor MFA (opcional) - Nome de usuário para rastreamento (opcional) |
| Microsoft Entra autenticação de token de usuário | - Token de Usuário - Impor MFA (opcional) - Nome de usuário para rastreamento (opcional) |
Propriedades de autenticação do aplicativo
| Nome da propriedade | Nome programático | Descrição |
|---|---|---|
| segurança federada da ID de Microsoft EntraAliases: Segurança Federada, Federada, Fed, AADFed |
FederatedSecurity | Um valor booliano que instrui o cliente a executar Microsoft Entra ID de autenticação federada. |
| Aliases SendX5c do Certificado de Aplicativo: Certificado de Aplicativo Enviar Certificado Público, SendX5c |
ApplicationCertificateSendX5c | Um valor booliano que instrui o cliente a executar o nome da entidade e a autenticação baseada no emissor. |
| Alias de impressão digital do certificado de aplicativo: AppCert |
ApplicationCertificateThumbprint | 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 do cliente do aplicativo. |
| Alias da ID do Cliente do Aplicativo: AppClientId |
ApplicationClientId | Um valor de cadeia de caracteres que fornece a ID do cliente do aplicativo a ser usada ao autenticar. |
| Alias da chave do aplicativo: AppKey |
ApplicationKey | Um valor de cadeia de caracteres que fornece a chave do aplicativo a ser usada ao autenticar usando um fluxo de segredo do aplicativo. |
| Nome do aplicativo para alias de rastreamento : 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. |
| Alias do token de aplicativo: AppToken |
ApplicationToken | Um valor de cadeia de caracteres que instrui o cliente a executar a autenticação de aplicativo com o token de portador especificado. |
| Alias de ID de autoridade: TenantId |
Authority | Um valor de cadeia de caracteres que fornece o nome ou a ID do locatário no qual o aplicativo está registrado. O valor padrão é microsoft.com. Para obter mais informações, consulte Microsoft Entra autoridade. |
| Aliases de região do Azure: AzureRegion, Região |
AzureRegion | 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 do aplicativo usar com a autenticação de identidade gerenciada. Use system para indicar a identidade atribuída pelo sistema. Essa propriedade não pode ser definida com um cadeia de conexão, apenas programaticamente. |
| Alias de nome diferenciado da entidade do certificado do aplicativo: entidade do certificado do aplicativo |
ApplicationCertificateSubjectDistinguishedName | Um valor de cadeia de caracteres que especifica o nome diferenciado da entidade do certificado do aplicativo. |
| Alias de nome diferenciado do emissor do certificado do aplicativo: emissor do certificado do aplicativo |
ApplicationCertificateIssuerDistinguishedName | Um valor de cadeia de caracteres que especifica o nome diferenciado do emissor do certificado do aplicativo. |
Combinações de propriedades com suporte para autenticação de aplicativo
Para autenticação de aplicativo, 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 do Aplicativo - ID da autoridade - Nome do aplicativo para rastreamento (opcional) |
| Autenticação de impressão digital do aplicativo Microsoft Entra | - ID do cliente do aplicativo - Impressão digital do certificado do aplicativo - ID da autoridade - Nome do aplicativo para rastreamento (opcional) |
| Microsoft Entra o assunto do aplicativo e a autenticação do emissor | - ID do cliente do aplicativo - Nome diferenciado da entidade do certificado do aplicativo - Nome diferenciado do emissor do certificado do aplicativo - ID da autoridade - Região do Azure (opcional) - Certificado de Aplicativo SendX5c (opcional) - Nome do Aplicativo para Rastreamento (opcional) |
| Autenticação do nome da entidade do aplicativo Microsoft Entra | - ID do cliente do aplicativo - Nome diferenciado da entidade do certificado do aplicativo- ID da autoridade- e região do Azure (opcional) - Nome do aplicativo para rastreamento (opcional) |
| autenticação de token de aplicativo Microsoft Entra | - Token de Aplicativo - Nome do Aplicativo para Rastreamento (opcional) |
Autenticação com um certificado de aplicativo
- O aplicativo deve ser configurado para aceitar o certificado especificado. Como autenticar com base em Microsoft Entra certificado do aplicativo.
- O aplicativo deve ser configurado como uma entidade de segurança autorizada no cluster Kusto relevante.
- O certificado precisa ser instalado no Repositório do Computador Local ou no Repositório de Usuários Atuais.
- A chave pública do certificado deve conter pelo menos 2.048 bits.
Propriedades de comunicação do cliente
| Nome da propriedade | Nome programático | Descrição |
|---|---|---|
| Aceitar | Aceitar | Um valor booliano que solicita que objetos de erro detalhados sejam retornados em caso de falha. |
| Streaming | Streaming | Um valor booliano que solicita que o cliente não acumule dados antes de fornecê-los ao chamador. Esse é o comportamento padrão. |
| Não compactado | Não compactado | Um valor booliano que solicita que o cliente não solicite compactação no nível do transporte. |
Observação
Quando o Streaming sinalizador está habilitado (como é o padrão), o SDK não armazena em buffer todos os dados de resposta na memória; em vez disso, ele "efetua pull" dos dados do serviço quando o chamador os solicita. Portanto, é essencial que, nesse caso, o chamador descarte corretamente os dados (como IDataReader) depois de terminar de ler os dados, pois a conexão de rede com o serviço é mantida aberta desnecessariamente.
Exemplos
Microsoft Entra autenticação federada de ID usando a identidade do usuário conectada no momento (o usuário será solicitado, se necessário)
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 Autenticação federada com dica de ID de usuário (o usuário será solicitado, se necessário)
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 autenticação de aplicativo federado usando 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}"
Usar Identidade gerenciada atribuída pelo sistema
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Usar Identidade gerenciada atribuída pelo usuário
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Microsoft Entra ID autenticação federada usando o token de usuário/aplicativo
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}"
Usando o retorno de chamada do provedor do token (será invocado sempre que um token for necessário)
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);
Usando um certificado 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);
Usando o certificado X.509 por impressão digital (o cliente tentará carregar o certificado do armazenamento local)
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}"
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de