使用 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 扩展。
若要安装 kqlmagic,请运行以下命令:
!pip install Kqlmagic --no-cache-dir --upgrade
若要加载 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 参数的字典: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 查询图表结果选择调色板
对于调色板列表:
%kql --palettes -popup_window
选择
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
来筛选数据。
运行查询以查看最大值为
DamageProperty
的前 10 个状态:%%kql StormEvents | summarize max(DamageProperty) by State | order by max_DamageProperty desc | take10
运行查询以提取第一个状态并将其设置到 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"
提示
若要接收有关所有可用配置的信息,请使用 %config Kqlmagic
。 若要排查和捕获 Kusto 错误(例如连接问题和不正确的查询),请使用 %config Kqlmagic.short_errors=False
示例笔记本
- 适用于 Azure 数据资源管理器的 kqlmagic 入门
- 适用于 Application Insights 的 kqlmagic 入门
- 适用于 Azure Monitor 日志的 kqlmagic 入门
- 使用 Python 将 kqlmagic 查询参数化
- 针对 kqlmagic 查询图表结果选择调色板