Cadeias de ligação do Kusto
As cadeias de ligação kusto fornecem as informações necessárias para que uma aplicação cliente Kusto estabeleça uma ligação a um ponto final de serviço kusto. As cadeias de ligação kusto são modeladas após o ADO.NET cadeias de ligação. Ou seja, o cadeia de ligação é uma lista delimitada por ponto e vírgula de pares de parâmetros name-value, opcionalmente prefixado por um único URI.
Por exemplo, a seguinte cadeia de ligação kusto começa com um URI que especifica o ponto final de serviço para comunicação: https://help.kusto.windows.net. Este URI está atribuído à Data Source propriedade. Em seguida, /Samples no cadeia de ligação representa a base de dados predefinida e é atribuída à Initial Catalog propriedade. Por fim, duas outras propriedades Fed e Accept, fornecem mais opções de configuração ou personalização para a ligação.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
Nota
- Os nomes das propriedades não são sensíveis às maiúsculas e minúsculas.
- Os valores das propriedades são sensíveis às maiúsculas e minúsculas.
- Os espaços entre pares de parâmetros name-value são ignorados.
- Um valor de propriedade que contenha um ponto e vírgula (
;), uma única aspa (') ou uma aspa dupla (") tem de estar entre aspas duplas.
Várias ferramentas de cliente Kusto suportam uma extensão sobre o prefixo URI do cadeia de ligação que permite um formato abreviado de @ClusterName/InitialCatalog. Por exemplo, estas ferramentas traduzem o cadeia de ligaçã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 ligação Kusto. Esta classe valida todas as cadeias de ligação e gera uma exceção de runtime se a validação falhar. Esta funcionalidade está presente em todos os sabores do SDK kusto.
Pontos finais fidedignos
Uma ligação com um ponto final do Kusto só pode ser estabelecida se esse ponto final for fidedigno.
O cliente Kusto confia em todos os pontos finais cuja parte de nome de anfitrião é emitida pelo serviço.
Por exemplo, pontos finais cujo nome de anfitrião DNS termina com kusto.windows.net.
Por predefinição, o cliente não estabelece ligações a outros pontos finais. Para permitir ligações a outros pontos finais, utilize a Kusto.Data.Common.KustoTrustedEndpoints classe para adicionar pontos finais à lista de pontos finais fidedignos. Utilize SetOverridePolicy para substituir a política predefinida 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 da cadeia de ligação
As tabelas seguintes listam todas as propriedades possíveis que podem ser incluídas numa cadeia de ligação 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 | Description |
|---|---|---|
| Versão do Cliente para Rastreio | TraceClientVersion | Ao rastrear a versão do cliente, utilize esta propriedade. |
| Aliases de Origem de Dados: Addr, Address, Network Address, Server |
DataSource | O URI que especifica o ponto final de serviço kusto. Por exemplo, https://mycluster.kusto.windows.net. |
| Alias de Catálogo Inicial: Base de Dados |
InitialCatalog | O nome da base de dados a utilizar por predefinição. Por exemplo, MyDatabase. |
| Alias de Consistência da Consulta: QueryConsistency |
QueryConsistency | Defina como ou strongconsistencyweakconsistency para determinar se a consulta deve sincronizar com os metadados antes de ser executada. |
Propriedades de autenticação do utilizador
| Nome da propriedade | Nome programático | Description |
|---|---|---|
| Segurança Federada Microsoft Entra IDAliases: Segurança Federada, Federado, Fed, AADFed |
FederatedSecurity | Um valor booleano que instrui o cliente a executar Microsoft Entra autenticação. |
| Alias do ID da Autoridade: TenantId |
Autoridade | Um valor de cadeia que fornece o nome ou ID do inquilino do utilizador. O valor predefinido é microsoft.com. Para obter mais informações, veja Microsoft Entra autoridade. |
| Impor Alias de MFA : MFA, EnforceMFA |
EnforceMfa | Um valor booleano opcional que instrui o cliente a adquirir um token de autenticação multifator. |
| Aliases de ID de Utilizador: UID, Utilizador |
UserID | Um valor de cadeia que instrui o cliente a efetuar a autenticação de utilizador com o nome de utilizador indicado. |
| Nome de Utilizador para Rastreio | TraceUserName | Um valor de cadeia opcional que comunica ao serviço o nome de utilizador a utilizar ao rastrear o pedido internamente. |
| Aliases de Token de Utilizador: UsrToken, UserToken |
UserToken | Um valor de cadeia que instrui o cliente a realizar a autenticação do utilizador com o token de portador especificado. ApplicationClientIdSubstitui , ApplicationKeye ApplicationToken. Se especificado, ignora o fluxo de autenticação de cliente real a favor do token fornecido. |
Combinações de propriedades suportadas para autenticação de utilizador
Para autenticação de utilizador, 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 propriedades |
|---|---|
| Autenticação de Pedidos de Microsoft Entra utilizador | - ID de Utilizador (opcional) - ID da Autoridade (opcional) - Impor MFA (opcional) - Nome de Utilizador para Rastreio (opcional) |
| Autenticação de Tokens de utilizador Microsoft Entra | - Token de Utilizador - Impor MFA (opcional) - Nome de Utilizador para Rastreio (opcional) |
Propriedades de autenticação de aplicações
| Nome da propriedade | Nome programático | Description |
|---|---|---|
| Segurança Federada Microsoft Entra IDAliases: Segurança Federada, Federado, Fed, AADFed |
FederatedSecurity | Um valor booleano que instrui o cliente a executar Microsoft Entra autenticação federada do ID. |
| Aliases SendX5c do Certificado de Aplicação: Certificado de Aplicação Enviar Certificado Público, SendX5c |
ApplicationCertificateSendX5c | Um valor booleano que instrui o cliente a executar o nome do requerente e a autenticação baseada no emissor. |
| Alias de Thumbprint do Certificado de Aplicação: AppCert |
ApplicationCertificateThumbprint | Um valor de cadeia que fornece o thumbprint do certificado de cliente a utilizar ao utilizar um fluxo de autenticação de certificado de cliente de aplicação. |
| Alias do ID do Cliente da Aplicação: AppClientId |
ApplicationClientId | Um valor de cadeia que fornece o ID de cliente da aplicação a utilizar ao autenticar. |
| Alias da Chave da Aplicação: AppKey |
ApplicationKey | Um valor de cadeia que fornece a chave de aplicação a utilizar ao autenticar com um fluxo de segredo da aplicação. |
| Nome da Aplicação para Alias de Rastreio: TraceAppName |
ApplicationNameForTracing | Um valor de cadeia opcional que comunica ao serviço o nome da aplicação a utilizar ao rastrear o pedido internamente. |
| Alias do Token de Aplicação: AppToken |
ApplicationToken | Um valor de cadeia que instrui o cliente a efetuar a autenticação da aplicação com o token de portador especificado. |
| Alias do ID da Autoridade: TenantId |
Autoridade | Um valor de cadeia que fornece o nome ou ID do inquilino no qual a aplicação está registada. O valor predefinido é microsoft.com. Para obter mais informações, veja Microsoft Entra autoridade. |
| Aliases da Região do Azure: AzureRegion, Região |
AzureRegion | Um valor de cadeia que fornece o nome da Região do Azure para autenticar. |
| ManagedServiceIdentity | EmbeddedManagedIdentity | Um valor de cadeia que indica ao cliente qual a identidade da aplicação a utilizar com a autenticação de identidade gerida. Utilize system para indicar a identidade atribuída pelo sistema. Esta propriedade não pode ser definida com um cadeia de ligação, apenas através de programação. |
| Alias de Nome Único do Requerente do Certificado de Aplicação: Requerente de Certificado de Aplicação |
ApplicationCertificateSubjectDistinguishedName | Um valor de cadeia que especifica o nome distinto do requerente do certificado de aplicação. |
| Alias de Nome Distinto do Emissor de Certificados de Aplicação: Emissor de Certificados de Aplicação |
ApplicationCertificateIssuerDistinguishedName | Um valor de cadeia que especifica o nome distinto do emissor de certificados de aplicação. |
Combinações de propriedades suportadas para autenticação de aplicações
Para autenticação de aplicações, 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 propriedades |
|---|---|
| Autenticação da Chave de Aplicação Microsoft Entra | - ID do Cliente da Aplicação – Chave da Aplicação – ID da Autoridade – Nome da Aplicação para Rastreio (opcional) |
| Autenticação de Thumbprint da Aplicação Microsoft Entra | - ID do Cliente da Aplicação – Thumbprint do Certificado de Aplicação – ID da Autoridade – Nome da Aplicação para Rastreio (opcional) |
| Microsoft Entra Assunto da Aplicação e Autenticação do Emissor | - ID do Cliente da Aplicação – Nome Único do Requerente do Certificado de Aplicação – Nome Distinguido do Emissor de Certificados de Aplicação – ID da Autoridade – Região do Azure (opcional) - SendX5c do Certificado de Aplicação (opcional) – Nome da Aplicação para Rastreio (opcional) |
| Autenticação do Nome do Requerente da Aplicação Microsoft Entra | - ID do Cliente da Aplicação – Nome Único do Requerente do Certificado de Aplicação – ID da Autoridade e Região do Azure (opcional) – Nome da Aplicação para Rastreio (opcional) |
| Autenticação do Token de Aplicação Microsoft Entra | - Token de Aplicação - Nome da Aplicação para Rastreio (opcional) |
Autenticação com um certificado de aplicação
- A aplicação deve ser configurada para aceitar o certificado especificado. Como autenticar com base no certificado de Microsoft Entra aplicação.
- A aplicação deve ser configurada como um principal autorizado no cluster do Kusto relevante.
- O certificado tem de ser instalado no Arquivo de Máquinas Locais ou no Arquivo de Utilizador Atual.
- A chave pública do certificado deve conter, pelo menos, 2048 bits.
Propriedades de comunicação do cliente
| Nome da propriedade | Nome programático | Description |
|---|---|---|
| Aceitar | Aceitar | Um valor booleano que pede que os objetos de erro detalhados sejam devolvidos na falha. |
| Transmissão em Fluxo | Transmissão em Fluxo | Um valor booleano que pede ao cliente que não acumule dados antes de os fornecer ao autor da chamada. Este é um comportamento predefinido. |
| Descomprimido | Descomprimido | Um valor booleano que pede ao cliente que não peça compressão ao nível do transporte. |
Nota
Quando o Streaming sinalizador está ativado (como é a predefinição), o SDK não intermédia todos os dados de resposta na memória; em vez disso, "extrai" os dados do serviço quando o autor da chamada os pede. Por conseguinte, é essencial que, neste caso, o autor da chamada elimine corretamente os dados (como IDataReader) assim que os dados forem lidos, uma vez que a ligação de rede ao serviço é mantida aberta desnecessariamente.
Exemplos
Microsoft Entra autenticação federada de ID com a identidade de utilizador atualmente iniciada (o utilizador 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 autenticação federada do ID com a sugestão de ID de utilizador (o utilizador 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 autenticação de aplicação federada de ID com 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}"
Utilizar a Identidade Gerida Atribuída pelo Sistema
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Utilizar a Identidade Gerida Atribuída pelo Utilizador
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Microsoft Entra autenticação federada do ID com o token de utilizador/aplicação
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}"
Utilizar a chamada de retorno do fornecedor de tokens (será invocada sempre que for necessário um 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);
Utilizar o 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);
Utilizar o certificado X.509 por thumbprint (o cliente tentará carregar o certificado a partir do arquivo 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
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários