Chaînes de connexion Kusto
Les chaînes de connexion Kusto fournissent les informations nécessaires pour qu’une application cliente Kusto établisse une connexion à un point de terminaison de service Kusto. Les chaînes de connexion Kusto sont modélisées d’après les chaînes de connexion ADO.NET. Autrement dit, le chaîne de connexion est une liste délimitée par des points-virgules de paires de paramètres nom-valeur, éventuellement précédées d’un URI unique.
Par exemple, le kusto chaîne de connexion suivant commence par un URI qui spécifie le point de terminaison de service pour la communication : https://help.kusto.windows.net. Cet URI est affecté à la Data Source propriété . Ensuite, /Samples dans le chaîne de connexion représente la base de données par défaut et est affectée à la Initial Catalog propriété . Enfin, deux autres propriétés, et Accept, Fed fournissent d’autres options de configuration ou de personnalisation pour la connexion.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
Notes
- Les noms de propriétés ne respectent pas la casse.
- Les valeurs de propriété respectent la casse.
- Les espaces entre les paires de paramètres nom-valeur sont ignorés.
- Une valeur de propriété qui contient un point-virgule (
;), un guillemet simple (') ou un guillemet double (") doit être placée entre guillemets doubles.
Plusieurs outils clients Kusto prennent en charge une extension sur le préfixe URI du chaîne de connexion qui permet un format abrégé de @ClusterName/InitialCatalog. Par exemple, ces outils traduisent le chaîne de connexion @help/Samples en https://help.kusto.windows.net/Samples; Fed=true.
Sur le plan programmatique, la classe C# Kusto.Data.KustoConnectionStringBuilder peut analyser et manipuler les chaînes de connexion Kusto. Cette classe valide toutes les chaînes de connexion et génère une exception au moment de l’exécution si la validation échoue. Cette fonctionnalité est présente dans toutes les versions du SDK Kusto.
Points de terminaison approuvés
Une connexion avec un point de terminaison Kusto ne peut être établie que si ce point de terminaison est approuvé.
Le client Kusto approuve tous les points de terminaison dont la partie de nom d’hôte est émise par le service.
Par instance, points de terminaison dont le nom d’hôte DNS se termine par kusto.windows.net.
Par défaut, le client n’établit pas de connexions à d’autres points de terminaison. Pour autoriser les connexions à d’autres points de terminaison, utilisez la Kusto.Data.Common.KustoTrustedEndpoints classe pour ajouter des points de terminaison à la liste des points de terminaison approuvés. Utilisez SetOverridePolicy pour remplacer la stratégie par défaut et AddTrustedHosts pour ajouter de nouvelles entrées à la stratégie existante.
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),
}
);
Propriétés de chaîne de connexion
Les tableaux suivants répertorient toutes les propriétés possibles qui peuvent être incluses dans un chaîne de connexion Kusto. Les tables fournissent également des noms d’alias pour chaque propriété. En outre, les tables indiquent les noms programmatiques associés à chaque propriété, qui représente le nom de la propriété dans l’objet Kusto.Data.KustoConnectionStringBuilder .
Propriétés générales
| Nom de la propriété | Nom programmatique | Description |
|---|---|---|
| Version du client pour le suivi | TraceClientVersion | Lorsque vous suivez la version du client, utilisez cette propriété. |
| Alias de source de données : Addr, Address, Network Address, Server |
DataSource | URI spécifiant le point de terminaison de service Kusto. Par exemple : https://mycluster.kusto.windows.net. |
| Alias de catalogue initial: base de données |
InitialCatalog | Nom de la base de données à utiliser par défaut. Par exemple : MyDatabase. |
| Alias de cohérence des requêtes: QueryConsistency |
QueryConsistency | Définissez sur strongconsistency ou weakconsistency pour déterminer si la requête doit se synchroniser avec les métadonnées avant de l’exécuter. |
Propriétés de l’authentification utilisateur
| Nom de la propriété | Nom programmatique | Description |
|---|---|---|
| sécurité fédérée de l’ID Microsoft EntraAlias: Federated Security, Federated, Fed, AADFed |
FederatedSecurity | Valeur booléenne qui indique au client d’effectuer Microsoft Entra authentification. |
| Alias d’ID d’autorité : TenantId |
Authority | Valeur de chaîne qui fournit le nom ou l’ID du locataire de l’utilisateur. La valeur par défaut est microsoft.com. Pour plus d’informations, consultez Microsoft Entra autorité. |
| Appliquer l’alias MFA : MFA, EnforceMFA |
EnforceMfa | Valeur booléenne facultative qui indique au client d’acquérir un jeton d’authentification multifacteur. |
| Alias d’ID utilisateur : UID, User |
UserID | Valeur de chaîne qui indique au client d’effectuer l’authentification de l’utilisateur avec le nom d’utilisateur indiqué. |
| Nom d’utilisateur pour le suivi | TraceUserName | Valeur de chaîne facultative qui indique au service quel nom d’utilisateur utiliser lors du suivi de la requête en interne. |
| Alias de jeton utilisateur : UsrToken, UserToken |
UserToken | Valeur de chaîne qui indique au client d’effectuer l’authentification de l’utilisateur avec le jeton du porteur spécifié. ApplicationClientIdRemplace , ApplicationKeyet ApplicationToken. S’il est spécifié, ignore le flux d’authentification client réel au profit du jeton fourni. |
Combinaisons de propriétés prises en charge pour l’authentification utilisateur
Pour l’authentification utilisateur, spécifiez AAD Federated Security comme true. Ensuite, choisissez l’un des modes d’authentification suivants et spécifiez les propriétés appropriées pour ce mode.
| Mode d'authentification | Noms de propriété |
|---|---|
| Authentification d’invite d’utilisateur Microsoft Entra | - ID utilisateur (facultatif) - ID d’autorité (facultatif) - Appliquer l’authentification multifacteur (facultatif) - Nom d’utilisateur pour le suivi (facultatif) |
| Authentification par jeton utilisateur Microsoft Entra | - Jeton utilisateur - Appliquer l’authentification multifacteur (facultatif) - Nom d’utilisateur pour le suivi (facultatif) |
Propriétés de l’authentification de l’application
| Nom de la propriété | Nom programmatique | Description |
|---|---|---|
| sécurité fédérée de l’ID Microsoft EntraAlias: Federated Security, Federated, Fed, AADFed |
FederatedSecurity | Valeur booléenne qui indique au client d’effectuer Microsoft Entra’authentification fédérée d’ID. |
| Alias SendX5c de certificat d’application : Certificat d’application Envoyer un certificat public, SendX5c |
ApplicationCertificateSendX5c | Valeur booléenne qui indique au client d’effectuer l’authentification basée sur le nom de l’objet et l’émetteur. |
| Alias d’empreinte du certificat d’application : AppCert |
ApplicationCertificateThumbprint | Valeur de chaîne qui fournit l’empreinte numérique du certificat client à utiliser lors de l’utilisation d’un flux d’authentification de certificat client d’application. |
| Alias d’ID client d’application : AppClientId |
ApplicationClientId | Valeur de chaîne qui fournit l’ID client d’application à utiliser lors de l’authentification. |
| Alias de clé d’application : AppKey |
ApplicationKey | Valeur de chaîne qui fournit la clé d’application à utiliser lors de l’authentification à l’aide d’un flux de secrets d’application. |
| Nom de l’application pour l’alias de suivi : TraceAppName |
ApplicationNameForTracing | Valeur de chaîne facultative qui indique au service le nom d’application à utiliser lors du suivi de la demande en interne. |
| Alias de jeton d’application : AppToken |
ApplicationToken | Valeur de chaîne qui indique au client d’effectuer l’authentification de l’application avec le jeton du porteur spécifié. |
| Alias d’ID d’autorité : TenantId |
Authority | Valeur de chaîne qui fournit le nom ou l’ID du locataire dans lequel l’application est inscrite. La valeur par défaut est microsoft.com. Pour plus d’informations, consultez autorité Microsoft Entra. |
| Alias de région Azure : AzureRegion, Region |
AzureRegion | Valeur de chaîne qui fournit le nom de la région Azure dans laquelle s’authentifier. |
| ManagedServiceIdentity | EmbeddedManagedIdentity | Valeur de chaîne qui indique au client quelle identité d’application utiliser avec l’authentification d’identité managée. Utilisez system pour indiquer l’identité affectée par le système. Cette propriété ne peut pas être définie avec un chaîne de connexion, uniquement par programmation. |
| Alias de nom unique du sujet du certificat d’application : Objet du certificat d’application |
ApplicationCertificateSubjectDistinguishedName | Valeur de chaîne qui spécifie le nom unique du sujet du certificat d’application. |
| Alias de nom unique de l’émetteur du certificat d’application : Émetteur de certificat d’application |
ApplicationCertificateIssuerDistinguishedName | Valeur de chaîne qui spécifie le nom unique de l’émetteur du certificat d’application. |
Combinaisons de propriétés prises en charge pour l’authentification d’application
Pour l’authentification de l’application, spécifiez AAD Federated Security comme true. Choisissez ensuite l’un des modes d’authentification suivants, puis spécifiez les propriétés appropriées pour ce mode.
| Mode d'authentification | Noms de propriété |
|---|---|
| Authentification par clé d’application Microsoft Entra | - Id client de l’application - Clé d’application - Id d’autorité - Nom de l’application pour le suivi (facultatif) |
| Authentification par empreinte numérique d’application Microsoft Entra | - Id client de l’application - Empreinte numérique du certificat d’application - ID d’autorité - Nom de l’application pour le suivi (facultatif) |
| Microsoft Entra l’objet de l’application et l’authentification de l’émetteur | - Id client de l’application - Nom unique de l’objet du certificat d’application - Nom unique de l’émetteur du certificat d’application - Id de l’autorité - Région Azure (facultatif) - Certificat d’application SendX5c (facultatif) - Nom de l’application pour le suivi (facultatif) |
| Authentification du nom du sujet de l’application Microsoft Entra | - Id client de l’application - Nom unique de l’objet du certificat d’application - Id d’autorité - et région Azure (facultatif) - Nom de l’application pour le suivi (facultatif) |
| Authentification par jeton d’application Microsoft Entra | - Jeton d’application - Nom de l’application pour le suivi (facultatif) |
Authentification avec un certificat d’application
- L’application doit être configurée pour accepter le certificat donné. Procédure d’authentification basée sur Microsoft Entra certificat de l’application.
- L’application doit être configurée en tant que principal autorisé dans le cluster Kusto approprié.
- Le certificat doit être installé dans le magasin ordinateur local ou dans le magasin de l’utilisateur actuel.
- La clé publique du certificat doit contenir au moins 2048 bits.
Propriétés de la communication client
| Nom de la propriété | Nom programmatique | Description |
|---|---|---|
| Acceptation | Accepter | Valeur booléenne qui demande que les objets d’erreur détaillés soient retournés en cas d’échec. |
| Diffusion en continu | Diffusion en continu | Valeur booléenne qui demande au client de ne pas accumuler de données avant de les fournir à l’appelant. Il s’agit d’un comportement par défaut. |
| Non compressé | Non compressé | Valeur booléenne qui demande au client de ne pas demander la compression au niveau du transport. |
Notes
Lorsque l’indicateur Streaming est activé (comme c’est le cas par défaut), le Kit de développement logiciel (SDK) ne met pas en mémoire tampon toutes les données de réponse ; au lieu de cela, il « extrait » les données du service lorsque l’appelant les demande. Par conséquent, il est essentiel que dans ce cas, l’appelant supprime correctement les données (par IDataReaderexemple) une fois qu’il a terminé la lecture des données, car la connexion réseau au service est maintenue ouverte inutilement.
Exemples
Authentification fédérée d’ID Microsoft Entra à l’aide de l’identité d’utilisateur actuellement connectée (l’utilisateur sera invité si nécessaire)
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}"
Authentification fédérée d’ID Microsoft Entra avec indicateur d’ID utilisateur (l’utilisateur sera invité si nécessaire)
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}"
Authentification d’application fédérée id Microsoft Entra à l’aide d’ApplicationClientId et 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}"
Utiliser une identité managée affectée par le système
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Utiliser une identité managée affectée par l’utilisateur
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Authentification fédérée d’ID Microsoft Entra à l’aide d’un jeton d’utilisateur/d’application
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}"
Utiliser le rappel du fournisseur de jetons (qui sera appelé chaque fois qu’un jeton est nécessaire)
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);
Utiliser un certificat 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);
Utiliser un certificat X.509 par empreinte numérique (le client tentera de charger le certificat à partir du magasin 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}"
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour