你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用 PowerShell 提供的 Kusto .NET 客户端库
适用于：✅Microsoft Fabric✅Azure 数据资源管理器
PowerShell 脚本可以使用 Kusto 客户端库，因为 PowerShell 原本就已与 .NET 库集成。 本文介绍了如何加载和使用这类客户端库来运行查询和管理命令。
先决条件
- 用于提取 zip 文件的存档工具，例如 7-Zip 或 WinRAR。
获取库
若要在 PowerShell 中使用 Kusto .NET 客户端库，请执行以下操作：
右键单击下载的包。 从菜单中选择存档工具并提取包内容。 如果存档工具在菜单中不可见，请选择“显示更多选项”。 提取将生成多个文件夹，其中一个文件夹名为 工具。
在 工具 文件夹中，有适用于不同 PowerShell 版本的不同子文件夹。 对于 PowerShell 版本 5.1，请使用 net472 文件夹。 对于 PowerShell 版本 7 或更高版本，请使用任何版本文件夹。 复制相关文件夹的路径。
从 PowerShell 加载相应库，将
<path>替换为复制的文件夹路径：[System.Reflection.Assembly]::LoadFrom("<path>\Kusto.Data.dll")应该会看到与下面类似的输出：
GAC 版本 位置 False v4.0.30319 C:\Downloads\tools\net472\Kusto.Data.dll
加载后，可以使用这些库来连接到群集和数据库。
连接到群集和数据库
使用以下方法之一向群集和数据库进行身份验证：
- 用户身份验证：在 Web 浏览器中提示用户验证其身份。
- 应用程序身份验证：创建 Microsoft 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.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)
控制跟踪
由于所有 PowerShell 应用程序都只有一个全局 PowerShell.exe.config 文件，因此通常库不能依赖 .NET 的 app.config 模型来访问其设置。 仍然可以使用编程模型进行跟踪。 有关更多信息，请参见控制跟踪。
可以改用以下方法：
启用控制台跟踪：
$traceListener = New-Object Kusto.Cloud.Platform.Utils.ConsoleTraceListener [Kusto.Cloud.Platform.Utils.TraceSourceManager]::RegisterTraceListener($traceListener)使用写入跟踪的文件夹位置的单个参数创建
Kusto.Cloud.Platform.Utils.RollingCsvTraceListener2对象。