Share via

使用 Jupyter Notebook 和 kqlmagic 延伸模組來分析 Azure Data Explorer

  • 發行項

Jupyter Notebook 是開放原始碼 Web 應用程式，可讓您建立及共用包含即時程式代碼、方程式、視覺效果和敘述文字的檔。 這適用於各種工作，例如數據清理和轉換、數值模擬、統計模型、數據視覺效果和機器學習。

Kqlmagic 會在 Jupyter Notebook 中擴充 Python 核心的功能，讓您可以原生執行 Kusto 查詢語言 (KQL) 查詢。 您可以使用與 轉譯 運算元整合的豐富 Plot.ly 連結庫，結合 Python 和 KQL 來查詢和可視化數據。 kqlmagic 延伸模組與 Jupyter Lab、Visual Studio Code Jupyter 擴充功能和 Azure Data Studio 兼容，支持的數據源包括 Azure Data Explorer、Azure 監視器記錄和 Application Insights。

在本文中，您將瞭解如何在 Jupyter Notebook 中使用 kqlmagic 來連線並查詢儲存在 Azure Data Explorer 中的數據。

必要條件

  • 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'

連線選項

若要簡化取得認證的程式，您可以在 連接字串 之後新增下列其中一個選項旗標。

選項 Description 範例語法
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。 cloud_environmenttimeoutobject_idmis_res_id// -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 除外。

查詢和轉譯圓形圖

%%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 資料框架

您可以在 Pandas 資料框架中存取 KQL 查詢的結果。 依變數 _kql_raw_result_ 存取最後一次執行查詢的結果，並輕鬆地將結果轉換為 Pandas 資料框架，如下所示：

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

範例

在許多分析案例中，您可能會想要建立包含許多查詢的可重複使用 Notebook，並將某個查詢的結果饋送給後續查詢。 下列範例會使用 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

範例筆記本

相關內容