Compartir a través de

Uso de bibliotecas cliente de .NET de Kusto desde PowerShell

  • Artículo

Los scripts de PowerShell pueden usar las bibliotecas cliente de Kusto, ya que PowerShell se integra intrínsecamente con las bibliotecas de .NET. En este artículo, aprenderá a cargar y usar las bibliotecas cliente para ejecutar consultas y comandos de administración.

Requisitos previos

  • Herramienta de archivado para extraer archivos ZIP, como 7-Zip o WinRAR.

Obtención de las bibliotecas

Para usar las bibliotecas cliente de .NET de Kusto en PowerShell:

  1. Descargue Microsoft.Azure.Kusto.Tools.

  2. Haga clic con el botón derecho en el paquete descargado. En el menú, seleccione la herramienta de archivado y extraiga el contenido del paquete. Si la herramienta de archivado no está visible en el menú, seleccione Mostrar más opciones. La extracción da como resultado varias carpetas, una de las cuales se denomina herramientas.

  3. Dentro de la carpeta de herramientas , hay diferentes subcarpetas que sirven para diferentes versiones de PowerShell. Para PowerShell versión 5.1, use la carpeta net472 . Para PowerShell versión 7 o posterior, use cualquiera de las carpetas de versión. Copie la ruta de acceso de la carpeta correspondiente.

  4. Desde PowerShell, cargue las bibliotecas y reemplace <path> por la ruta de acceso de carpeta copiada:

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

    Debería ver una salida similar a la siguiente:

    GAC Versión Location
    False v4.0.30319 C:\Downloads\tools\net472\Kusto.Data.dll

Una vez cargado, puede usar las bibliotecas para conectarse a un clúster y una base de datos.

Conexión a un clúster y una base de datos

Autentíquese en un clúster y una base de datos con uno de los métodos siguientes:

  • Autenticación de usuario: pida al usuario que compruebe su identidad en un explorador web.
  • Autenticación de aplicaciones: cree una aplicación MS Entra y use las credenciales para la autenticación.
  • Autenticación de la CLI de Azure: inicie sesión en la CLI de Azure en la máquina y Kusto recuperará el token de la CLI de Azure.

Seleccione la pestaña correspondiente.

Una vez que ejecute la primera consulta o comando, este método abrirá una ventana interactiva del explorador para la autorización del usuario.

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

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

Ejecución de una consulta

Cree un proveedor de consultas y ejecute consultas Lenguaje de consulta Kusto.

En el ejemplo siguiente se define una consulta take simple para muestrear los datos. Para ejecutar la consulta, reemplace por <TableName> el nombre de una tabla de la base de datos. Antes de ejecutar la consulta, la clase ClientRequestProperties se usa para establecer un identificador de solicitud de cliente y un tiempo de espera del servidor. A continuación, se ejecuta la consulta y el conjunto de resultados tiene el formato y la ordenación.

$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

Salida

StartTime EndTime EpisodeID Id. de evento State EventType InjuriesDirect InjuriesIndirect DeathsDirect = DeathsIndirect
2007-12-30 16:00:00 2007-12-30 16:05:00 11749 64588 GEORGIA Viento de tormenta 0 0 0 0
2007-12-20 07:50:00 2007-12-20 07:53:00 12554 68796 MISISIPÍ Viento de tormenta 0 0 0 0
2007-09-29 08:11:00 2007-09-29 08:11:00 11091 61032 ATLÁNTICO SUR Spout de agua 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 Lluvia intensa 0 0 0 0

Ejecución de un comando de administración

Cree un proveedor de administración de CSL y ejecute comandos de administración.

En el ejemplo siguiente se ejecuta un comando de administración para comprobar el estado del clúster.

$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"

Salida

IsHealthy = True

Para obtener más instrucciones sobre cómo ejecutar comandos de administración con las bibliotecas cliente de Kusto, consulte Creación de una aplicación para ejecutar comandos de administración.

Ejemplo

En el ejemplo siguiente se muestra el proceso de carga de las bibliotecas, la autenticación y la ejecución de una consulta en el clúster accesible help públicamente.

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

Contenido relacionado