使用 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 证书应存储在可从笔记本访问的文件中。 可以在连接字符串中引用此文件。

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';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 参数的字典:resourceclient_id/object_id/mis_res_idcloud_environmenttimeout -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 支持大多数图表,但是 timepivotpivotchartladderchart 除外。 除 kindysplitaccumulate 之外的所有属性都支持 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

示例笔记本