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 Fed
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 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 , ApplicationKey y 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
- La aplicación debe configurarse para aceptar el certificado especificado. Autenticación basada en el certificado de Microsoft Entra aplicación.
- La aplicación debe configurarse como una entidad de seguridad autorizada en el clúster de Kusto correspondiente.
- El certificado debe instalarse en el almacén de máquinas locales o en el almacén de usuario actual.
- 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 IDataReader
ejemplo, ) 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}"
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta:Enviar y ver comentarios de