Cadenas de conexión de Kusto

Las cadenas de conexión de Kusto proporcionan la información necesaria para que una aplicación cliente de Kusto establezca una conexión a un punto de conexión de servicio de Kusto. Las cadenas de conexión de Kusto se modelan según las cadenas de conexión de ADO.NET. Es decir, el cadena de conexión es una lista delimitada por punto y coma de pares de parámetros nombre-valor, prefijo opcionalmente por un solo URI.

Por ejemplo, el siguiente cadena de conexión kusto comienza con un URI que especifica el punto de conexión de servicio para la comunicación: https://help.kusto.windows.net. Este URI se asigna a la Data Source propiedad . A continuación, /Samples dentro de la cadena de conexión representa la base de datos predeterminada y se asigna a la Initial Catalog propiedad . Por último, dos otras propiedades y FedAccept, proporcionan más opciones de configuración o personalización para la conexión.

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

Nota:

• Los nombres de propiedad no distinguen mayúsculas de minúsculas.
• Los valores de las propiedades distinguen mayúsculas de minúsculas.
• Se omiten los espacios entre pares de parámetros de nombre-valor.
• Un valor de propiedad que contiene un punto y coma (;), una comilla simple (') o una comilla doble (") se debe incluir entre comillas dobles.

Varias herramientas de cliente de Kusto admiten una extensión sobre el prefijo URI de la cadena de conexión que permite un formato abreviado de @ClusterName/InitialCatalog. Por ejemplo, estas herramientas traducen el cadena de conexión @help/Samples a https://help.kusto.windows.net/Samples; Fed=true.

Mediante programación, la clase C# Kusto.Data.KustoConnectionStringBuilder puede analizar y manipular cadenas de conexión de Kusto. Esta clase valida todas las cadenas de conexión y genera una excepción en tiempo de ejecución si se produce un error en la validación. Esta funcionalidad está presente en todas las variantes del SDK de Kusto.

Puntos de conexión de confianza

Una conexión con un punto de conexión de Kusto solo se puede establecer si ese punto de conexión es de confianza. El cliente de Kusto confía en todos los puntos de conexión cuyo elemento de nombre de host emite el servicio. Por ejemplo, los puntos de conexión cuyo nombre de host DNS termina con kusto.windows.net.

De forma predeterminada, el cliente no establece conexiones a otros puntos de conexión. Para permitir conexiones a otros puntos de conexión, use la Kusto.Data.Common.KustoTrustedEndpoints clase para agregar puntos de conexión a la lista de puntos de conexión de confianza. Use SetOverridePolicy para invalidar la directiva predeterminada y AddTrustedHosts para agregar nuevas entradas a la directiva 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),
    }
);

Propiedades de las cadenas de conexión

En las tablas siguientes se enumeran todas las propiedades posibles que se pueden incluir en un cadena de conexión de Kusto. Las tablas también proporcionan nombres de alias para cada propiedad. Además, las tablas indican los nombres de programación asociados a cada propiedad, que representa el nombre de la propiedad en el Kusto.Data.KustoConnectionStringBuilder objeto .

Propiedades generales

Nombre de propiedad	Nombre de programación	Descripción
Versión del cliente para el seguimiento	TraceClientVersion	Al realizar el seguimiento de la versión del cliente, use esta propiedad.
Alias de origen de datos: Addr, Address, Network Address, Server	DataSource	Identificador URI que especifica el punto de conexión de servicio de Kusto. Por ejemplo, https://mycluster.kusto.windows.net.
Alias de catálogo inicial: base de datos	InitialCatalog	Nombre de la base de datos que se va a usar de manera predeterminada. Por ejemplo, MyDatabase.
Alias de coherencia de consulta : QueryConsistency	QueryConsistency	Establezca en strongconsistency o weakconsistency para determinar si la consulta debe sincronizarse con los metadatos antes de ejecutarse.

Propiedades de autenticación del usuario

Nombre de propiedad	Nombre de programación	Descripción
Microsoft Entra id. de seguridad federadaAlias: Seguridad federada, Federada, Fed, AADFed	FederatedSecurity	Valor booleano que indica al cliente que realice Microsoft Entra autenticación.
Alias del identificador de autoridad: TenantId	Autoridad	Valor de cadena que proporciona el nombre o el identificador del inquilino del usuario. El valor predeterminado es microsoft.com. Para obtener más información, consulte Microsoft Entra autoridad.
Aplicar alias de MFA : MFA, EnforceMFA	EnforceMfa	Valor booleano opcional que indica al cliente que adquiera un token de autenticación multifactor.
Alias de identificador de usuario: UID, Usuario	UserID	Valor de cadena que indica al cliente que realice la autenticación de usuario con el nombre de usuario indicado.
Nombre de usuario para el seguimiento	TraceUserName	Valor de cadena opcional que informa al servicio que se usará el nombre de usuario al realizar el seguimiento de la solicitud internamente.
Alias de token de usuario: UsrToken, UserToken	UserToken	Valor de cadena que indica al cliente que realice la autenticación de usuario con el token de portador especificado. Invalida ApplicationClientId, ApplicationKeyy ApplicationToken. Si se especifica, omite el flujo de autenticación de cliente real en favor del token proporcionado.

Combinaciones de propiedades admitidas para la autenticación de usuario

Para la autenticación de usuario, especifique AAD Federated Security como true. A continuación, elija uno de los siguientes modos de autenticación y especifique las propiedades pertinentes para ese modo.

Modo de autenticación	Nombres de propiedad
autenticación del símbolo del sistema de usuario de Microsoft Entra	- Id. de usuario (opcional) - Id. de autoridad (opcional) - Exigir MFA (opcional) - Nombre de usuario para el seguimiento (opcional)
autenticación de token de usuario de Microsoft Entra	- Token de usuario: aplicar MFA (opcional): nombre de usuario para el seguimiento (opcional)

Propiedades de autenticación de la aplicación

Nombre de propiedad	Nombre de programación	Descripción
Microsoft Entra id. de seguridad federadaAlias: Seguridad federada, Federada, Fed, AADFed	FederatedSecurity	Valor booleano que indica al cliente que realice Microsoft Entra autenticación federada de identificador.
Alias de SendX5c de certificado de aplicación: Certificado de aplicación Enviar certificado público, SendX5c	ApplicationCertificateSendX5c	Valor booleano que indica al cliente que realice la autenticación basada en el nombre del firmante y el emisor.
Alias de huella digital del certificado de aplicación : AppCert	ApplicationCertificateThumbprint	Valor de cadena que proporciona la huella digital del certificado de cliente que se va a usar al usar un flujo de autenticación de certificados de cliente de aplicación.
Alias de identificador de cliente de aplicación: AppClientId	ApplicationClientId	Valor de cadena que proporciona el identificador de cliente de la aplicación que se va a usar al autenticarse.
Alias de clave de aplicación: AppKey	ApplicationKey	Valor de cadena que proporciona la clave de aplicación que se va a usar al autenticarse mediante un flujo de secretos de aplicación.
Nombre de la aplicación para el alias de seguimiento : TraceAppName	ApplicationNameForTracing	Valor de cadena opcional que notifica al servicio el nombre de la aplicación que se va a usar al realizar el seguimiento interno de la solicitud.
Alias de token de aplicación: AppToken	ApplicationToken	Valor de cadena que indica al cliente que realice la autenticación de la aplicación con el token de portador especificado.
Alias del identificador de autoridad: TenantId	Autoridad	Valor de cadena que proporciona el nombre o el identificador del inquilino en el que se registra la aplicación. El valor predeterminado es microsoft.com. Para obtener más información, consulte Microsoft Entra autoridad.
Alias de región de Azure: AzureRegión, Región	AzureRegion	Valor de cadena que proporciona el nombre de la región de Azure en la que se va a autenticar.
ManagedServiceIdentity	EmbeddedManagedIdentity	Valor de cadena que indica al cliente qué identidad de aplicación se va a usar con la autenticación de identidad administrada. Use system para indicar la identidad asignada por el sistema. Esta propiedad no se puede establecer con un cadena de conexión, solo mediante programación.
Alias de nombre distintivo del firmante del certificado de aplicación: firmante del certificado de aplicación	ApplicationCertificateSubjectDistinguishedName	Valor de cadena que especifica el nombre distintivo del firmante del certificado de aplicación.
Alias de nombre distintivo del emisor de certificados de aplicación: emisor de certificados de aplicación	ApplicationCertificateIssuerDistinguishedName	Valor de cadena que especifica el nombre distintivo del emisor del certificado de aplicación.

Combinaciones de propiedades admitidas para la autenticación de aplicaciones

Para la autenticación de aplicaciones, especifique AAD Federated Security como true. A continuación, elija uno de los siguientes modos de autenticación y especifique las propiedades pertinentes para ese modo.

Modo de autenticación	Nombres de propiedad
Autenticación de clave de aplicación de Microsoft Entra	- Id. de cliente de aplicación- Clave de aplicación- Id . de autoridad - Nombre de la aplicación para el seguimiento (opcional)
Autenticación de huella digital de aplicación de Microsoft Entra	- Id. de cliente de aplicación- Huella digital del certificado de aplicación- Id. de entidad - Nombre de aplicación para el seguimiento (opcional)
Microsoft Entra aplicación sujeto y autenticación del emisor	- Id . de cliente de aplicación- Nombre distintivo del firmante del certificado de aplicación- Nombre distintivo del emisor de certificado de aplicación- Id . de autoridad- Región de Azure (opcional)- Envío de certificado de aplicaciónX5c (opcional) - Nombre de aplicación para el seguimiento (opcional)
Autenticación de nombre de sujeto de aplicación de Microsoft Entra	- Id . de cliente de aplicación- Nombre distintivo del firmante del certificado de aplicación- Id . de autoridad y región de Azure (opcional) - Nombre de aplicación para el seguimiento (opcional)
Autenticación de token de aplicación de Microsoft Entra	- Token de aplicación: nombre de aplicación para el seguimiento (opcional)

Autenticación con un certificado de aplicación

1. La aplicación debe configurarse para aceptar el certificado especificado. Autenticación basada en el certificado de Microsoft Entra aplicación.
2. La aplicación debe configurarse como una entidad de seguridad autorizada en el clúster de Kusto correspondiente.
3. El certificado debe instalarse en el almacén de máquinas locales o en el almacén de usuario actual.
4. La clave pública del certificado debe contener al menos 2048 bits.

Propiedades de comunicación del cliente

Nombre de propiedad	Nombre de programación	Descripción
Accept	Aceptar	Valor booleano que solicita que se devuelvan objetos de error detallados en caso de error.
Streaming	Streaming	Valor booleano que solicita al cliente que no acumula datos antes de proporcionarlos al autor de la llamada. Este es el comportamiento predeterminado.
Sin comprimir	Sin comprimir	Valor booleano que solicita al cliente que no solicita la compresión de nivel de transporte.

Nota:

Cuando la Streaming marca está habilitada (como es el valor predeterminado), el SDK no almacena en búfer todos los datos de respuesta en la memoria; en su lugar, "extrae" los datos del servicio cuando el autor de la llamada lo solicita. Por lo tanto, es esencial que, en este caso, el autor de la llamada elimine correctamente los datos (por IDataReaderejemplo, ) una vez que haya terminado de leer los datos, ya que la conexión de red al servicio se mantiene abierta innecesariamente.

Ejemplos

Microsoft Entra autenticación federada de identificador mediante la identidad de usuario que ha iniciado sesión actualmente (si es necesario, se le pedirá al usuario).

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. autenticación federada con la sugerencia de identificador de usuario (se le pedirá al usuario si es necesario)

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. autenticación de aplicación federada mediante ApplicationClientId y 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}"

Con una identidad administrada asignada por el sistema

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

Con una identidad administrada asignada por el usuario

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

Microsoft Entra id. de autenticación federada mediante el token de usuario o aplicación

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

Con devolución de llamada del proveedor de tokens (se invocará cada vez que se requiera 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);

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

Con certificado X.509 mediante huella digital (el cliente intentará cargar el certificado desde el almacén 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}"