Freigeben über

Verwenden der Kusto-.NET-Clientbibliotheken aus PowerShell

  • Artikel

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer

PowerShell-Skripts können die Kusto-Clientbibliotheken verwenden, da PowerShell inhärent in .NET-Bibliotheken integriert wird. In diesem Artikel erfahren Sie, wie Sie die Clientbibliotheken laden und verwenden, um Abfragen und Verwaltungsbefehle auszuführen.

Voraussetzungen

  • Ein Archivierungstool zum Extrahieren von ZIP-Dateien, z. B. 7-Zip oder WinRAR.

Abrufen der Bibliotheken

So verwenden Sie die Kusto .NET-Clientbibliotheken in PowerShell:

  1. Laden Sie Microsoft.Azure.Kusto.Tools herunter.

  2. Klicken Sie mit der rechten Maustaste auf das heruntergeladene Paket. Wählen Sie im Menü Ihr Archivierungstool aus, und extrahieren Sie den Paketinhalt. Wenn das Archivierungstool nicht im Menü angezeigt wird, wählen Sie " Weitere Optionen anzeigen" aus. Die Extraktion führt zu mehreren Ordnern, von denen eines der benannten Tools ist.

  3. Innerhalb des Toolsordners gibt es verschiedene Unterordner für verschiedene PowerShell-Versionen. Verwenden Sie für PowerShell Version 5.1 den Net472-Ordner . Verwenden Sie für PowerShell, Version 7 oder höher, einen der Versionsordner. Kopieren Sie den Pfad des relevanten Ordners.

  4. Laden Sie die Bibliotheken aus PowerShell, und ersetzen <path> Sie sie durch den kopierten Ordnerpfad:

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

    Es sollte eine Ausgabe angezeigt werden, die Folgendem ähnelt:

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

Nach dem Laden können Sie die Bibliotheken verwenden, um eine Verbindung mit einem Cluster und einer Datenbank herzustellen.

Herstellen einer Verbindung mit einem Cluster und einer Datenbank

Authentifizieren sie sich bei einem Cluster und einer Datenbank mit einer der folgenden Methoden:

  • Benutzerauthentifizierung: Fordern Sie den Benutzer auf, seine Identität in einem Webbrowser zu überprüfen.
  • Anwendungsauthentifizierung: Erstellen Sie eine Microsoft Entra-App , und verwenden Sie die Anmeldeinformationen für die Authentifizierung.
  • Azure CLI-Authentifizierung: Melden Sie sich bei der Azure CLI auf Ihrem Computer an, und Kusto ruft das Token von Azure CLI ab.

Wählen Sie die relevante Registerkarte aus.

Nachdem Sie die erste Abfrage oder den ersten Befehl ausgeführt haben, öffnet diese Methode ein interaktives Browserfenster für die Benutzerautorisierung.

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

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

Ausführen einer Abfrage

Erstellen Sie einen Abfrageanbieter, und führen Sie Kusto-Abfragesprache Abfragen aus.

Im folgenden Beispiel wird eine einfache Take-Abfrage zum Beispiel der Daten definiert. Ersetzen Sie zum Ausführen der Abfrage <TableName> den Namen einer Tabelle in Ihrer Datenbank. Vor dem Ausführen der Abfrage wird die ClientRequestProperties-Klasse verwendet, um eine Clientanforderungs-ID und ein Servertimeout festzulegen. Anschließend wird die Abfrage ausgeführt, und das Resultset wird formatiert und sortiert.

$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 InjuriesDirect InjuriesIndirect DeathsDirect DeathsIndirect
2007-12-30 16:00:00 2007-12-30 16:05:00 11749 64588 GEORGIA Sturm 0 0 0 0
2007-12-20 07:50:00 2007-12-20 07:53:00 12,554 68796 MISSISSIPPI Sturm 0 0 0 0
2007-09-29 08:11:00 2007-09-29 08:11:00 11091 61032 ATLANTIC SOUTH Wasserauslauf 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 Starker Regen 0 0 0 0

Ausführen eines Verwaltungsbefehls

Erstellen Sie einen CSL-Administratoranbieter, und führen Sie Verwaltungsbefehle aus.

Im folgenden Beispiel wird ein Verwaltungsbefehl ausgeführt, um den Status des Clusters zu überprüfen.

$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

Weitere Informationen zum Ausführen von Verwaltungsbefehlen mit den Kusto-Clientbibliotheken finden Sie unter Erstellen einer App zum Ausführen von Verwaltungsbefehlen.

Beispiel

Im folgenden Beispiel wird das Laden der Bibliotheken, die Authentifizierung und das Ausführen einer Abfrage für den öffentlich zugänglichen help Cluster veranschaulicht.

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

Steuern der Ablaufverfolgung

Da es nur eine globale PowerShell.exe.config Datei für alle PowerShell-Anwendungen gibt, können Bibliotheken in der Regel nicht auf . Das App.config-Modell von NET für den Zugriff auf ihre Einstellungen. Sie können das programmgesteuerte Modell weiterhin für die Ablaufverfolgung verwenden. Weitere Informationen finden Sie unter Steuern der Ablaufverfolgung.

Sie können stattdessen die folgenden Methoden verwenden:

  • Aktivieren sie die Ablaufverfolgung auf der Konsole:

    $traceListener = New-Object Kusto.Cloud.Platform.Utils.ConsoleTraceListener
[Kusto.Cloud.Platform.Utils.TraceSourceManager]::RegisterTraceListener($traceListener)

  • Erstellen Sie ein Kusto.Cloud.Platform.Utils.RollingCsvTraceListener2 Objekt mit einem einzelnen Argument des Ordnerspeicherorts, an dem Ablaufverfolgungen geschrieben werden.

Zugehöriger Inhalt