Cadenas de conexión de Kusto

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

Kusto cadena de conexión 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 único URI.

Por ejemplo, el siguiente cadena de conexión de 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 del cadena de conexión representa la base de datos predeterminada y se asigna a la Initial Catalog propiedad . Por último, otras dos propiedades Fed y Accept, 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 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.

Mediante programación, la clase de C# Kusto.Data.KustoConnectionStringBuilder puede analizar y manipular kusto cadena de conexión s. 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 todos los tipos del SDK de Kusto.

Puntos de conexión de confianza

Solo se puede establecer una conexión con un punto de conexión de Kusto si ese punto de conexión es de confianza. El cliente de Kusto confía en todos los puntos de conexión cuyo dominio 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<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)),
    }
);

Propiedades de las cadenas de conexión

En las tablas siguientes se enumeran todas las propiedades posibles que se pueden incluir en una cadena de conexión de Kusto y se proporcionan nombres de alias para cada propiedad. Además, las tablas anotan el nombre mediante programación asociado 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	La propiedad usada al realizar el seguimiento de la versión del cliente.
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 predeterminado de la base de datos. Por ejemplo, MyDatabase.
Alias de coherencia de consulta: QueryConsistency	QueryConsistency	Establezca en o strongconsistency 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
Alias de seguridad federada de Microsoft Entra ID: Seguridad federada, Federada, Fed, AADFed	FederatedSecurity	Valor booleano que indica al cliente que realice la autenticación de Microsoft Entra.
Alias de 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 autoridad de Microsoft Entra.
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 notifica al servicio que se va a 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 de solicitud 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- Exigir 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
Alias de seguridad federada de Microsoft Entra ID: Seguridad federada, Federada, Fed, AADFed	FederatedSecurity	Valor booleano que indica al cliente que realice la autenticación federada de Id. de Microsoft Entra.
Alias sendX5c del 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 aplicación para alias de seguimiento : TraceAppName	ApplicationNameForTracing	Valor de cadena opcional que informa al servicio que se usará el nombre de la aplicación al realizar el seguimiento de la solicitud internamente.
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 de 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 autoridad de Microsoft Entra.
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	- Identificador de cliente de aplicación- Clave de aplicación- Identificador de autoridad - Nombre de aplicación para el seguimiento (opcional)
Autenticación de huella digital de aplicaciones de Microsoft Entra	- Id. de cliente de aplicación- Huella digital del certificado de aplicación- Id. de autoridad - Nombre de aplicación para el seguimiento (opcional)
Microsoft Entra Application Subject and Issuer Authentication	- Identificador de cliente de la aplicación- Nombre distintivo del firmante del certificado de aplicación- Nombre distintivo del emisor del certificado de aplicación- Identificador 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	- Identificador de cliente de aplicación: nombre distintivo del firmante del certificado de aplicación: identificador 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 la aplicación Microsoft Entra.
2. La aplicación debe configurarse como una entidad de seguridad autorizada en el entorno de Kusto pertinente.
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	Accept	Valor booleano que solicita que se devuelvan objetos de error detallados en caso de error.
Streaming	Streaming	Valor booleano que solicita que el cliente proporcione datos inmediatamente al autor de la llamada sin acumularlos primero. El streaming es un comportamiento predeterminado.
Sin comprimir	Sin comprimir	Valor booleano que indica al cliente que evite solicitar compresión de nivel de transporte.

Nota:

Cuando la Streaming marca está habilitada (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, como IDataReader. Una vez que haya terminado de leer los datos, ya que la conexión de red al servicio se mantiene abierta innecesariamente.

Ejemplos

Autenticación federada de Id. de Microsoft Entra con la identidad de usuario actual

En el ejemplo siguiente se muestra cómo configurar una conexión a un servicio kusto mediante el identificador de Microsoft Entra para la autenticación federada. Cuando sea necesario, se solicita al usuario las credenciales.

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

Autenticación federada de Microsoft Entra ID con sugerencia de identificador de usuario

En el ejemplo siguiente se muestra cómo configurar una conexión a un servicio kusto mediante el identificador de Microsoft Entra para la autenticación federada y rellena previamente la identidad del usuario mediante la userID variable . Cuando sea necesario, se solicita al usuario las credenciales.

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

Autenticación de aplicación federada de Microsoft Entra ID con ApplicationClientId y ApplicationKey

En el ejemplo siguiente se muestra cómo autenticarse en un servicio kusto mediante el identificador de Entra de Microsoft para la autenticación federada con un identificador y una clave de cliente de aplicación.

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

Autenticación federada de Id. de Microsoft Entra con tokens de usuario y aplicación

En el ejemplo siguiente se muestra cómo configurar una conexión a un servicio kusto mediante el identificador de Microsoft Entra con un token de acceso de usuario o un token de acceso de aplicación.

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

Autenticación con devolución de llamada del proveedor de tokens

En el ejemplo siguiente se muestra cómo autenticarse en un servicio kusto mediante el identificador de Microsoft Entra con una devolución de llamada del proveedor de tokens personalizado. El token se invoca cada vez que se requiere un token.

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

Autenticación con certificado X.509

En el ejemplo siguiente se muestra cómo autenticarse en un servicio kusto mediante el identificador de Entra de Microsoft para la autenticación federada con un certificado de aplicación.

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

Autenticación con huella digital del certificado X.509

En el ejemplo siguiente se muestra cómo configurar una conexión a un servicio kusto mediante el identificador de Microsoft Entra con una huella digital de certificado de aplicación. El cliente intenta cargar el certificado desde un almacén local.

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