使用 PowerShell 提供的 Kusto .NET 客户端库

  • 项目

PowerShell 脚本可以使用 Kusto 客户端库，因为 PowerShell 原本就已与 .NET 库集成。 本文介绍了如何加载和使用这类客户端库来运行查询和管理命令。

先决条件

  • 用于提取 zip 文件的存档工具，例如 7-Zip 或 WinRAR。

获取库

若要在 PowerShell 中使用 Kusto .NET 客户端库，请执行以下操作：

  1. 下载 Microsoft.Azure.Kusto.Tools。

  2. 右键单击下载的包。 从菜单中选择存档工具并提取包内容。 如果存档工具在菜单中不可见，请选择“显示更多选项”。 提取将生成多个文件夹，其中一个文件夹名为 工具。

  3. 在 工具 文件夹中，有适用于不同 PowerShell 版本的不同子文件夹。 对于 PowerShell 版本 5.1，请使用 net472 文件夹。 对于 PowerShell 版本 7 或更高版本，请使用任何版本文件夹。 复制相关文件夹的路径。

  4. 从 PowerShell 加载相应库，将 <path> 替换为复制的文件夹路径：

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

    应该会看到与下面类似的输出：

    GAC 版本 位置
    False v4.0.30319 C:\Downloads\tools\net472\Kusto.Data.dll

加载后，可以使用这些库来连接到群集和数据库。

连接到群集和数据库

使用以下方法之一向群集和数据库进行身份验证：

  • 用户身份验证：在 Web 浏览器中提示用户验证其身份。
  • 应用程序身份验证：创建 MS Entra 应用并使用凭据进行身份验证。
  • Azure CLI 身份验证：登录到计算机上的 Azure CLI，Kusto 将从 Azure CLI 检索令牌。

选择相关选项卡。

运行第一个查询或命令后，此方法将打开用于获得用户授权的交互式浏览器窗口。

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

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

运行查询

创建查询提供程序并运行 Kusto 查询语言查询。

以下示例定义了一个简单的 take 查询来对数据进行采样。 若要运行该查询，请将 <TableName> 替换为数据库中某个表的名称。 在运行查询之前，ClientRequestProperties 类用于设置客户端请求 ID 和服务器超时。 然后，将运行查询，系统会对结果集进行格式设置和排序。

$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

输出

StartTime EndTime EpisodeID EventID 状态 EventType InjuriesDirect InjuriesIndirect DeathsDirect DeathsIndirect
2007-12-30 16:00:00 2007-12-30 16:05:00 11749 64588 佐治亚州 雷雨大风 0 0 0 0
2007-12-20 07:50:00 2007-12-20 07:53:00 12554 68796 密西西比州 雷雨大风 0 0 0 0
2007-09-29 08:11:00 2007-09-29 08:11:00 11091 61032 大西洋南部 水龙卷风 0 0 0 0
2007-09-20 21:57:00 2007-09-20 22:05:00 11078 60913 佛罗里达州 龙卷风 0 0 0 0
2007-09-18 20:00:00 2007-09-19 18:00:00 11074 60904 佛罗里达州 暴雨 0 0 0 0

运行管理命令

创建 CSL 管理员提供程序并运行管理命令。

以下示例运行了管理命令来检查群集的运行状况。

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

输出

IsHealthy = True

有关使用 Kusto 客户端库运行管理命令的更多指南，请参阅创建应用以运行管理命令。

示例

以下示例演示了在可公开访问的 help 群集上加载库、进行身份验证和执行查询的过程。

#  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.chinaeast2.kusto.chinacloudapi.cn;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)

相关内容