使用 Jupyter 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。

本文介绍如何在 Jupyter Notebook 中使用 kqlmagic 连接到 Azure 数据资源管理器中存储的数据并对其进行查询。

先决条件

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

安装 kqlmagic

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

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

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

  2. 若要加载 kqlmagic 扩展，请运行以下命令：

    %reload_ext Kqlmagic

连接到群集

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

Microsoft Entra 代码方法提示 MSAL 交互式登录。 你将收到一个身份验证代码。

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

提示

  • 若要参数化连接字符串，请使用不带引号的值，因为这些值将解释为 Python 表达式。
  • 若要简化获取凭据的过程，请参阅连接选项。

群集连接示例

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

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

连接选项

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

选项 说明 示例语法
try_azcli_login 尝试从 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 登录选项：

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

显示连接信息

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

%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 
| take10
| render piechart title="My Pie Chart by State"

查询和呈现时间表

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

注意

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

自定义图表颜色

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

  1. 对于调色板列表：

    %kql --palettes -popup_window

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

    %%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| 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)

示例

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

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

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

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

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

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

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

  4. 运行 help 命令：

    %kql --help "help"

提示

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

示例笔记本

相关内容