Share via

Utiliser des bibliothèques clientes Kusto .NET à partir de PowerShell

  • Article

Les scripts PowerShell peuvent utiliser les bibliothèques clientes Kusto, car PowerShell s’intègre par nature 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 permettant d’extraire des fichiers zip, comme 7-Zip ou WinRAR.

Obtenir les bibliothèques

Pour utiliser les bibliothèques clientes Kusto .NET dans PowerShell :

  1. Télécharger Microsoft.Azure.Kusto.Tools.

  2. 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 plus d’options. L’extraction aboutit à plusieurs dossiers, dont l’un est nommé tools.

  3. Dans le dossier tools , il existe différents sous-dossiers qui s’adressent à 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é.

  4. À partir de PowerShell, chargez les bibliothèques, en remplaçant par <path> le chemin du dossier copié :

    [System.Reflection.Assembly]::LoadFrom("<path>\Kusto.Data.dll")

    Le résultat doit ressembler à ce qui suit :

    GAC Version Location
    False v4.0.30319 C:\Downloads\tools\net472\Kusto.Data.dll

Une fois le chargement effectué, 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 MS Entra et utilisez les informations d’identification pour l’authentification.
  • Authentification Azure CLI : Connectez-vous à Azure CLI sur votre machine et Kusto récupérera 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 de l’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 Langage de requête Kusto requêtes.

L’exemple suivant définit une requête take simple pour échantillonner les données. Pour exécuter la requête, remplacez par <TableName> 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 12554 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 case activée 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, d’authentification et d’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)

Contenu connexe