次の方法で共有


Jupyter Notebook と Kqlmagic 拡張機能を使用して Azure Data Explorer 内のデータを分析する

Jupyter Notebook は、ライブ コード、数式、視覚化、およびストーリー テキストを含むドキュメントを作成して共有できるオープンソースの Web アプリケーションです。 データのクリーンと変換、数値シミュレーション、統計モデリング、データ視覚化、機械学習など、さまざまなタスクに役立ちます。

Kqlmagic は、Jupyter Notebook の Python カーネルの機能を拡張し、Kusto 照会言語 (KQL) クエリをネイティブに実行できるようにします。 Python と KQL を組み合わせて、レンダー オペレーターと統合された豊富な Plot.ly ライブラリを使用してデータのクエリと視覚化を行うことができます。 kqlmagic 拡張機能は、Jupyter Lab、Visual Studio Code Jupyter 拡張機能、Azure Data Studio と互換性があり、サポートされているデータ ソースには、Azure Data エクスプローラー、Azure Monitor ログ、アプリケーション インサイトが含まれます。

この記事では、Jupyter Notebook で kqlmagic を使用して、Azure Data エクスプローラー に格納されているデータに接続してクエリを実行する方法について説明します。

前提条件

  • Microsoft アカウントまたは Microsoft Entra ユーザー ID。 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
    

クラスターへの接続

クラスターに接続する任意の方法のタブを選択します。

Note

可能な場合は、証明書の認証方法を使用することをお勧めします。

Microsoft Entra 証明書は、ノートブックからアクセスできるファイルに格納する必要があります。 このファイルは、接続文字列で参照できます。

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

ヒント

  • 接続文字列をパラメーター化するには、引用符で囲まれていない値を使用して Python 式として解釈します。
  • 資格情報を取得するプロセスを簡略化するには、「接続オプション」を参照してください

クラスター接続の例

次のコマンドでは、Microsoft Entra コードメソッドを使用して、クラスターでホストされているデータベースに対して Samples 認証を help 行います。 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 パラメーターを持つディクショナリが必要です。 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 を除くすべての属性でサポートされています。

クエリを実行して円グラフをレンダリングする

%%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

Note

これらのグラフは対話形式です。 特定の時間を拡大するには、時間範囲を選択します。

グラフの色をカスタマイズする

既定のカラー パレットが好みでない場合は、パレット オプションを使用してグラフをカスタマイズします。 使用可能なパレットは次の場所にあります。 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)

多くの分析シナリオでは、多数のクエリを含む再利用可能なノートブックを作成し、あるクエリから後続のクエリに結果をフィードすることが必要な場合があります。 次の例では、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を使用します

サンプル ノートブック