使用 Jupyter Notebook 和 kqlmagic 擴充功能來分析 Azure 數據總管中的數據

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

Kqlmagic 會在 Jupyter Notebook 中擴充 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 擴充功能。

1. 若要安裝 kqlmagic，請執行下列命令：

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

2. 若要載入 kqlmagic 擴充功能，請執行下列命令：

   %reload_ext Kqlmagic
   

連接到叢集

選取您慣用方法的索引標籤，以連線到您的叢集。

注意

建議您盡可能使用驗證的憑證方法。

[MSSQLSERVER 的通訊協定內容]

Microsoft Entra 憑證應該儲存在可從筆記本存取的檔案中。 此檔案可以在 連接字串 中參考。

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'

程式碼

Microsoft Entra 程式代碼方法會提示 MSAL 互動式登入。 您將會收到要輸入以進行驗證的程式代碼。

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

應用程式金鑰

Microsoft Entra 應用程式方法允許使用 Microsoft Entra 應用程式識別碼和金鑰進行非互動式登入。

%kql AzureDataExplorer://tenant='<tenant-id>';clientid='<aad-appid>';clientsecret='<aad-appkey>';cluster='<cluster-name>';database='<database-name>'

使用者名稱和密碼

Microsoft Entra 使用者名稱和密碼方法只能在公司網路上運作。 如果未提供使用者名稱，則會提示使用者提供密碼。

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

匿名

匿名驗證相當於沒有驗證，僅支援本機叢集。

%kql azureDataExplorer://anonymous;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 
| 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. 執行查詢以檢視前 10 個狀態，其最大值 DamageProperty為 ：

   %%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. 執行說明命令：

   %kql --help "help"
   

提示

若要接收所有可用組態的相關信息， 請使用 %config Kqlmagic。 若要針對 Kusto 錯誤進行疑難解答並擷取，例如連線問題和不正確的查詢，請使用 %config Kqlmagic.short_errors=False

範例筆記本

• 開始使用適用於 Azure 數據總管的 kqlmagic
• 開始使用 Application Insights 的 kqlmagic
• 開始使用適用於 Azure 監視器記錄的 kqlmagic
• 使用 Python 將 kqlmagic 查詢參數化
• 選擇 kqlmagic 查詢圖表結果的色彩調色盤

相關內容

• 學習 Kusto 查詢語言 （KQL）