Utiliser les bibliothèques client Kusto .NET à partir de PowerShell
S’applique à : ✅Microsoft Fabric✅Azure Data Explorer
Les scripts PowerShell peuvent utiliser les bibliothèques de client Kusto, car PowerShell s’intègre de manière inhérente aux bibliothèques .NET. Dans cet article, vous allez apprendre à charger et utiliser les bibliothèques clientes pour exécuter des requêtes et des commandes de gestion.
Prérequis
- Outil d’archivage pour extraire des fichiers ZIP, tels que 7-Zip ou WinRAR.
Obtenir les bibliothèques
Pour utiliser les bibliothèques clientes Kusto .NET dans PowerShell :
Télécharger
Microsoft.Azure.Kusto.Tools.Cliquez avec le bouton droit sur le package téléchargé. Dans le menu, sélectionnez votre outil d’archivage et extrayez le contenu du package. Si l’outil d’archivage n’est pas visible dans le menu, sélectionnez Afficher d’autres options. L’extraction génère plusieurs dossiers, dont l’un est nommé outils.
Dans le dossier outils , il existe différents sous-dossiers qui correspondent à différentes versions de PowerShell. Pour PowerShell version 5.1, utilisez le dossier net472 . Pour PowerShell version 7 ou ultérieure, utilisez l’un des dossiers de version. Copiez le chemin d’accès du dossier approprié.
À partir de PowerShell, chargez les bibliothèques, en remplaçant
<path>par le chemin du dossier copié :[System.Reflection.Assembly]::LoadFrom("<path>\Kusto.Data.dll")Le résultat doit ressembler à ce qui suit :
GAC Version Emplacement False v4.0.30319 C :\Downloads\tools\net472\Kusto.Data.dll
Une fois chargé, vous pouvez utiliser les bibliothèques pour vous connecter à un cluster et à une base de données.
Se connecter à un cluster et à une base de données
Authentifiez-vous auprès d’un cluster et d’une base de données avec l’une des méthodes suivantes :
- Authentification de l’utilisateur : invitez l’utilisateur à vérifier son identité dans un navigateur web.
- Authentification de l’application : créez une application Microsoft Entra et utilisez les informations d’identification pour l’authentification.
- Authentification Azure CLI : Connectez-vous à Azure CLI sur votre machine, et Kusto récupère le jeton à partir d’Azure CLI.
Sélectionnez l’onglet approprié.
Une fois que vous avez exécuté votre première requête ou commande, cette méthode ouvre une fenêtre de navigateur interactive pour l’autorisation utilisateur.
$clusterUrl = "<Your cluster URI>"
$databaseName = "<Your database name>"
$kcsb = New-Object Kusto.Data.KustoConnectionStringBuilder($clusterUrl, $databaseName)
Exécuter une requête
Créez un fournisseur de requêtes et exécutez des requêtes Langage de requête Kusto.
L’exemple suivant définit une requête de prise simple pour échantillonner les données. Pour exécuter la requête, remplacez <TableName> par le nom d’une table dans votre base de données. Avant d’exécuter la requête, la classe ClientRequestProperties est utilisée pour définir un ID de demande client et un délai d’expiration du serveur. Ensuite, la requête est exécutée et le jeu de résultats est mis en forme et trié.
$queryProvider = [Kusto.Data.Net.Client.KustoClientFactory]::CreateCslQueryProvider($kcsb)
$query = "<TableName> | take 5"
Write-Host "Executing query: '$query' with connection string: '$($kcsb.ToString())'"
# Optional: set a client request ID and set a client request property (e.g. Server Timeout)
$crp = New-Object Kusto.Data.Common.ClientRequestProperties
$crp.ClientRequestId = "MyPowershellScript.ExecuteQuery." + [Guid]::NewGuid().ToString()
$crp.SetOption([Kusto.Data.Common.ClientRequestProperties]::OptionServerTimeout, [TimeSpan]::FromSeconds(30))
# Run the query
$reader = $queryProvider.ExecuteQuery($query, $crp)
# Do something with the result datatable
# For example: print it formatted as a table, sorted by the "StartTime" column in descending order
$dataTable = [Kusto.Cloud.Platform.Data.ExtendedDataReader]::ToDataSet($reader).Tables[0]
$dataView = New-Object System.Data.DataView($dataTable)
$dataView | Sort StartTime -Descending | Format-Table -AutoSize
Sortie
| StartTime | EndTime | EpisodeID | EventID | État | Type d’événement | InjuriesDirect | InjuriesIndirect | DeathsDirect | DeathsIndirect |
|---|---|---|---|---|---|---|---|---|---|
| 2007-12-30 16:00:00 | 2007-12-30 16:05:00 | 11749 | 64588 | GEORGIE | Vent d’orage | 0 | 0 | 0 | 0 |
| 2007-12-20 07:50:00 | 2007-12-20 07:53:00 | 12,554 | 68796 | MISSISSIPPI | Vent d’orage | 0 | 0 | 0 | 0 |
| 2007-09-29 08:11:00 | 2007-09-29 08:11:00 | 11091 | 61032 | ATLANTIQUE SUD | Spout d’eau | 0 | 0 | 0 | 0 |
| 2007-09-20 21:57:00 | 2007-09-20 22:05:00 | 11078 | 60913 | FLORIDE | Tornade | 0 | 0 | 0 | 0 |
| 2007-09-18 20:00:00 | 2007-09-19 18:00:00 | 11074 | 60904 | FLORIDE | Fortes précipitations | 0 | 0 | 0 | 0 |
Exécuter une commande de gestion
Créez un fournisseur d’administration CSL et exécutez des commandes de gestion.
L’exemple suivant exécute une commande de gestion pour vérifier l’intégrité du cluster.
$adminProvider = [Kusto.Data.Net.Client.KustoClientFactory]::CreateCslAdminProvider($kcsb)
$command = [Kusto.Data.Common.CslCommandGenerator]::GenerateDiagnosticsShowCommand()
Write-Host "Executing command: '$command' with connection string: '$($kcsb.ToString())'"
# Run the command
$reader = $adminProvider.ExecuteControlCommand($command)
# Read the results
$reader.Read() # this reads a single row/record. If you have multiple ones returned, you can read in a loop
$isHealthy = $Reader.GetBoolean(0)
Write-Host "IsHealthy = $isHealthy"
Sortie
IsHealthy = True
Pour plus d’informations sur l’exécution de commandes de gestion avec les bibliothèques clientes Kusto, consultez Créer une application pour exécuter des commandes de gestion.
Exemple
L’exemple suivant illustre le processus de chargement des bibliothèques, de l’authentification et de l’exécution d’une requête sur le cluster accessible help publiquement.
# This is an example of the location from where you extract the Microsoft.Azure.Kusto.Tools package
# Make sure you load the types from a local directory and not from a remote share
# Make sure you load the version compatible with your PowerShell version (see explanations above)
# Use `dir "$packagesRoot\*" | Unblock-File` to make sure all these files can be loaded and executed
$packagesRoot = "C:\Microsoft.Azure.Kusto.Tools\tools\net472"
# Load the Kusto client library and its dependencies
[System.Reflection.Assembly]::LoadFrom("$packagesRoot\Kusto.Data.dll")
# Define the connection to the help cluster and database
$clusterUrl = "https://help.kusto.windows.net;Fed=True"
$databaseName = "Samples"
# MS Entra user authentication with interactive prompt
$kcsb = New-Object Kusto.Data.KustoConnectionStringBuilder($clusterUrl, $databaseName)
# Run a simple query
$queryProvider = [Kusto.Data.Net.Client.KustoClientFactory]::CreateCslQueryProvider($kcsb)
$query = "StormEvents | take 5"
$reader = $queryProvider.ExecuteQuery($query, $crp)
Contrôle du traçage
Étant donné qu’il n’existe qu’un seul fichier global PowerShell.exe.config pour toutes les applications PowerShell, les bibliothèques généralement ne peuvent pas s’appuyer sur . Modèle app.config de NET pour accéder à ses paramètres. Vous pouvez toujours utiliser le modèle programmatique pour le suivi. Pour plus d’informations, consultez contrôle du suivi.
Vous pouvez utiliser les méthodes suivantes à la place :
Activez le suivi dans la console :
$traceListener = New-Object Kusto.Cloud.Platform.Utils.ConsoleTraceListener [Kusto.Cloud.Platform.Utils.TraceSourceManager]::RegisterTraceListener($traceListener)Créez un
Kusto.Cloud.Platform.Utils.RollingCsvTraceListener2objet avec un seul argument de l’emplacement du dossier où les traces sont écrites.