使用 Notebook 和 kqlmagic 分析 Azure 数据资源管理器中的数据

Jupyter Notebook 是一个开源的 Web 应用程序，可用于创建和共享包含实时代码、公式、可视化效果和叙述性文本的文档。它可用于各种任务，例如数据清理和转换、数值模拟、统计建模、数据可视化和机器学习。

Kqlmagic 扩展了 Jupyter Notebook 中的 Python 内核功能，因此你可以本机运行 Kusto 查询语言 (KQL) 查询。可以使用与 render 运算符集成的丰富 Plot.ly 库来组合 Python 和 KQL 以查询和可视化数据。 Kqlmagic 扩展与 Jupyter Lab、Visual Studio Code Jupyter 扩展和 Azure Data Studio 兼容，支持的数据源包括 Azure 数据资源管理器、Azure Monitor 日志和 Application Insights。

本文介绍如何使用 Notebook 中的 Kqlmagic 扩展连接到 Azure 数据资源管理器中存储的数据并查询存储的数据。

Prerequisites

Microsoft 帐户或 Microsoft Entra 用户标识。无需 Azure 订阅。
已在本地计算机上安装 Notebook。如果未安装，请使用 Azure Data Studio。
Python 3.6. 若要将 Jupyter Notebook 内核版本更改为 Python 3.6，请选择“内核”“更改内核”>“Python 3.6”。

Install kqlmagic

安装并加载 kqlmagic 扩展后，可以在笔记本中编写 KQL 查询。如果内核停止或结果不符合预期，请重新加载 kqlmagic 扩展。

若要安装 kqlmagic，请运行以下命令：

!pip install Kqlmagic --no-cache-dir  --upgrade

若要加载 kqlmagic 扩展，请运行以下命令：
```
%reload_ext Kqlmagic
```

连接到群集

选择用于连接到群集的首选方法所对应的选项卡。

Note

建议尽可能使用证书身份验证方法。

Microsoft Entra 证书应存储在可从笔记本访问的文件中。可以在连接字符串中引用此文件。

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'

Microsoft Entra 代码方法会提示Microsoft身份验证库（MSAL）交互式登录。你会收到用于身份验证输入的代码。

%kql AzureDataExplorer://code;cluster='<cluster-name>';database='<database-name>'

Microsoft Entra 应用程序方法允许使用 Microsoft Entra 应用程序 ID 和密钥进行非交互式登录。

%kql AzureDataExplorer://tenant='<tenant-id>';clientid='<aad-appid>';clientsecret='<aad-appkey>';cluster='<cluster-name>';database='<database-name>'

Microsoft Entra 用户名和密码方法仅适用于企业网络。如果提供了用户名但未提供密码，则系统会提示用户提供密码。

%kql AzureDataExplorer://username='<username>';password='<password>';cluster='<cluster-name>';database='<database-name>'

匿名身份验证相当于无身份验证，仅支持用于本地群集。

%kql azureDataExplorer://anonymous;cluster='<cluster-name>';database='<database-name>'

Tip

若要参数化连接字符串，请使用未引号的值，因为它们被解释为 Python 表达式。
若要简化获取凭据的过程，请参阅连接选项。

群集连接示例

以下命令使用 Microsoft Entra 代码方法对 Samples 群集上托管的 help 数据库进行身份验证。对于非 Microsoft Entra 用户，请将租户名称 Microsoft.com 替换为 Microsoft Entra 租户。

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

Connection options

若要简化获取凭据的过程，可以在连接字符串后面添加以下选项标志之一。

Option	Description	Example syntax
try_azcli_login	尝试从 Azure CLI 获取身份验证凭据。期望你已经通过 Azure CLI 登录。请参阅使用 Azure CLI 的连接示例。	`-try_azcli_login`
try_azcli_login_subscription	尝试基于指定的订阅从 Azure CLI 获取身份验证凭据。	`-try_azcli_login_subscription=<subscription_id>`
try_vscode_login	尝试在 Azure 帐户登录期间从 Visual Studio Code 获取身份验证凭据。	`-try_vscode_login`
try_msi	尝试从 MSI 本地终结点获取身份验证凭据。需要一个包含可选 MSI 参数的字典：`resource`、`client_id`/`object_id`/`mis_res_id`、`cloud_environment`、`timeout`。	`-try_msi={"client_id":<id>}`
try_token	使用指定的令牌进行身份验证。需要一个包含 Azure AD v1 或 v2 令牌属性的字典。	`-try_token={"tokenType":"bearer","accessToken":"<token>"}`

使用 Azure CLI 的连接示例

可以在连接字符串后面添加上表中所述的任何选项。以下示例使用 Azure CLI 登录选项作为身份验证方法：

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

Note

此选项假定已使用 Azure CLI 登录到 Azure。如果未登录，弹出窗口会提示登录到 Azure。

显示连接信息

若要查看所有现有连接，请运行以下命令：

%kql --conn

若要检查特定连接的详细信息，请运行以下命令：

%kql --conn <database-name>@<cluster-name>

查询和可视化

查询数据使用 render 运算符，而可视化数据使用 ploy.ly 库。此查询和可视化操作提供了使用本机 KQL 的集成体验。

Kqlmagic 支持大多数图表，但是 timepivot、pivotchart 和 ladderchart 除外。除 kind、ysplit 和 accumulate 之外的所有属性都支持 Render。

查询和呈现饼图

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take 10
| render piechart title="My Pie Chart by State"

查询和呈现时间表

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

Note

这些图表是交互式的。选择时间范围可放大到特定时间。

自定义图表颜色

如果不喜欢默认调色板，可使用调色板选项自定义图表。在此处可找到可用的调色板：针对 kqlmagic 查询图表结果选择调色板

对于调色板列表：
```
%kql --palettes -popup_window
```

选择 cool 调色板并重新呈现查询：

%%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take 10
| render piechart title="My Pie Chart by State"

使用 Python 将查询参数化

Kqlmagic 可用于在 Kusto 查询语言与 Python 之间进行简单的交换。若要了解详细信息，请访问以下链接：使用 Python 将 kqlmagic 查询参数化

在 KQL 查询中使用 Python 变量

可在查询中使用 Python 变量的值来筛选数据：

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

将查询结果转换到 Pandas DataFrame

可在 Pandas DataFrame 中访问 KQL 查询的结果。通过变量 _kql_raw_result_ 访问上次执行的查询结果，并轻松地将结果转换到 Pandas DataFrame 中，如下所示：

df = _kql_raw_result_.to_dataframe()
df.head(10)

Example

在很多分析方案中，可能需要创建包含多个查询的可复用笔记本，并将结果从一个查询馈送到后续查询中。以下示例使用 Python 变量 statefilter 来筛选数据。

运行查询以查看最大值为 DamageProperty 的前 10 个状态：

%%kql
StormEvents
| summarize max(DamageProperty) by State
| order by max_DamageProperty desc
| take 10

运行查询以提取第一个状态并将其设置到 Python 变量中：

df = _kql_raw_result_.to_dataframe()
statefilter =df.loc[0].State
statefilter

使用 let 语句和 Python 变量运行查询：

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state)
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

运行 help 命令：
```
%kql --help "help"
```

Tip

若要接收有关所有可用配置的信息，请使用 %config Kqlmagic。
若要排查和捕获 Kusto 错误（例如连接问题和不正确的查询），请使用 %config Kqlmagic.short_errors=False

Sample notebooks

了解 Kusto 查询语言 (KQL)

Last updated on 2025-07-25

Compartir a través de

使用 Notebook 和 kqlmagic 分析 Azure 数据资源管理器中的数据

Prerequisites

Install kqlmagic

连接到群集

群集连接示例

Connection options

使用 Azure CLI 的连接示例

显示连接信息

查询和可视化

查询和呈现饼图

查询和呈现时间表

自定义图表颜色

使用 Python 将查询参数化

在 KQL 查询中使用 Python 变量

将查询结果转换到 Pandas DataFrame

Example

Sample notebooks

Related content

Recursos adicionales