使用 Jupyter Notebook 和 kqlmagic 擴充功能來分析 Azure 數據總管中的數據
Jupyter Notebook 是開放原始碼 Web 應用程式，可讓您建立及共用包含即時程式代碼、方程式、視覺效果和敘事文字的檔。 它適用於各種工作，例如數據清理和轉換、數值模擬、統計模型、數據視覺效果和機器學習。
Kqlmagic 擴展了 Jupyter 筆記本中 Python 核心的功能，因此您可以原生執行 Kusto 查詢語言 (KQL)查詢。 您可以使用與轉譯運算子整合的豐富的 Plot.ly 程式庫結合 Python 與 KQL 來查詢及視覺化資料。 kqlmagic 延伸模組與 Jupyter Lab、Visual Studio Code Jupyter 擴充功能和 Azure Data Studio 相容，且支持的數據源包括 Azure 數據總管、Azure 監視器記錄和 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 | 嘗試從 Visual Studio Code Azure 帳戶登入取得驗證認證。 | -try_vscode_login |
| try_msi | 嘗試從 MSI 本機端點取得驗證認證。 預期具有選擇性 MSI 參數的字典：resource、、/mis_res_idobject_id/client_idcloud_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>
查詢並以視覺方式呈現
使用 轉譯運算子 查詢數據，並使用 ploy.ly 連結庫將數據可視化。 此查詢與視覺效果會提供使用原生 KQL 的整合式體驗。 Kqlmagic 支援除了 、 pivotchart和 ladderchart以外的timepivot大部分圖表。 除了 、 ysplit和accumulate之外kind，所有屬性都支持轉譯。
查詢和轉譯餅圖
%%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
注意
這些圖表是互動式圖表。 選取要放大特定時間的時間範圍。
自訂圖表色彩
如果您不喜歡預設調色盤，請使用調色盤選項自定義圖表。 您可以在這裡找到可用的調色盤： 為您的 kqlmagic 查詢圖表結果選擇色彩調色盤
如需調色盤清單：
%kql --palettes -popup_windowcool選取調色盤，然後再次轉譯查詢：%%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)
範例
在許多分析案例中，您可能想要建立可重複使用的筆記本，其中包含許多查詢，並將結果從一個查詢饋送至後續查詢。 下列範例會使用 Python 變數 statefilter 來篩選數據。
執行查詢以檢視前 10 個狀態，其最大值
DamageProperty為 ：%%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"執行說明命令：
%kql --help "help"
提示
若要接收所有可用組態的相關信息， 請使用 %config Kqlmagic。 若要針對 Kusto 錯誤進行疑難解答並擷取，例如連線問題和不正確的查詢，請使用 %config Kqlmagic.short_errors=False
範例筆記本
- 開始使用適用於 Azure 數據總管的 kqlmagic
- 開始使用 Application Insights 的 kqlmagic
- 開始使用適用於 Azure 監視器記錄的 kqlmagic
- 使用 Python 將 kqlmagic 查詢參數化
- 選擇 kqlmagic 查詢圖表結果的色彩調色盤