Usare librerie client .NET Kusto da PowerShell

  • Articolo

Gli script di PowerShell possono usare le librerie client Kusto, perché PowerShell si integra intrinsecamente con le librerie .NET. Questo articolo illustra come caricare e usare le librerie client per eseguire query e comandi di gestione.

Prerequisiti

  • Strumento di archiviazione per estrarre file ZIP, ad esempio 7-Zip o WinRAR.

Ottenere le librerie

Per usare le librerie client Kusto .NET in PowerShell:

  1. Scaricare Microsoft.Azure.Kusto.Tools.

  2. Fare clic con il pulsante destro del mouse sul pacchetto scaricato. Dal menu selezionare lo strumento di archiviazione ed estrarre il contenuto del pacchetto. Se lo strumento di archiviazione non è visibile dal menu, selezionare Mostra altre opzioni. L'estrazione restituisce più cartelle, una delle quali è denominata strumenti.

  3. All'interno della cartella degli strumenti sono disponibili sottocartelle diverse per diverse versioni di PowerShell. Per PowerShell versione 5.1, usare la cartella net472 . Per PowerShell versione 7 o successiva, usare una delle cartelle della versione. Copiare il percorso della cartella pertinente.

  4. Da PowerShell caricare le librerie, sostituendo <path> con il percorso della cartella copiato:

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

    L'output dovrebbe essere simile al seguente:

    GAC Versione Location
    Falso v4.0.30319 C:\Downloads\tools\net472\Kusto.Data.dll

Dopo il caricamento, è possibile usare le librerie per connettersi a un cluster e a un database.

Connettersi a un cluster e a un database

Eseguire l'autenticazione in un cluster e in un database con uno dei metodi seguenti:

  • Autenticazione utente: Richiedere all'utente di verificare la propria identità in un Web browser.
  • Autenticazione dell'applicazione:creare un'app MS Entra e usare le credenziali per l'autenticazione.
  • Autenticazione dell'interfaccia della riga di comando di Azure: Accedere all'interfaccia della riga di comando di Azure nel computer e Kusto recupererà il token dall'interfaccia della riga di comando di Azure.

Selezionare la scheda pertinente.

Dopo aver eseguito la prima query o il primo comando, questo metodo aprirà una finestra interattiva del browser per l'autorizzazione utente.

$clusterUrl = "<Your cluster URI>"
$databaseName = "<Your database name>"

$kcsb = New-Object Kusto.Data.KustoConnectionStringBuilder($clusterUrl, $databaseName)

Eseguire una query

Creare un provider di query ed eseguire Linguaggio di query Kusto query.

Nell'esempio seguente viene definita una semplice query take per campionare i dati. Per eseguire la query, sostituire <TableName> con il nome di una tabella nel database. Prima di eseguire la query, la classe ClientRequestProperties viene usata per impostare un ID richiesta client e un timeout del server. La query viene quindi eseguita e il set di risultati viene formattato e ordinato.

$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

Output

StartTime EndTime EpisodeID EventID State EventType LesioniDirect LesioniIndirect DeathsDirect MortiIndirect
2007-12-30 16:00:00 2007-12-30 16:05:00 11749 64588 GEORGIA Vento di tempesta 0 0 0 0
2007-12-20 07:50:00 2007-12-20 07:53:00 12554 68796 MISSISSIPPI Vento di tempesta 0 0 0 0
2007-09-29 08:11:00 2007-09-29 08:11:00 11091 61032 SUD ATLANTICO Spout acqua 0 0 0 0
2007-09-20 21:57:00 2007-09-20 22:05:00 11078 60913 FLORIDA Tornado 0 0 0 0
2007-09-18 20:00:00 2007-09-19 18:00:00 11074 60904 FLORIDA Pioggia intensa 0 0 0 0

Eseguire un comando di gestione

Creare un provider di amministrazione CSL ed eseguire i comandi di gestione.

Nell'esempio seguente viene eseguito un comando di gestione per controllare l'integrità del 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"

Output

IsHealthy = True

Per altre indicazioni su come eseguire i comandi di gestione con le librerie client Kusto, vedere Creare un'app per eseguire i comandi di gestione.

Esempio

Nell'esempio seguente viene illustrato il processo di caricamento delle librerie, dell'autenticazione e dell'esecuzione di una query nel cluster accessibile help pubblicamente.

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

Contenuti correlati