Bagikan melalui

Menggunakan Jupyter Notebook dan ekstensi kqlmagic untuk menganalisis data di Azure Data Explorer

  • Artikel

Jupyter Notebook adalah aplikasi web sumber terbuka yang memungkinkan Anda membuat dan berbagi dokumen yang berisi kode langsung, persamaan, visualisasi, dan teks narasi. Ini berguna untuk berbagai tugas, seperti pembersihan dan transformasi data, simulasi numerik, pemodelan statistik, visualisasi data, dan pembelajaran mesin.

Kqlmagic memperluas kemampuan kernel Python di Jupyter Notebook sehingga Anda dapat menjalankan kueri Bahasa Kueri Kusto (KQL) secara asli. Anda dapat menggabungkan Python dan KQL untuk mengkueri dan memvisualisasikan data menggunakan pustaka Plot.ly kaya yang terintegrasi dengan operator render . Ekstensi kqlmagic kompatibel dengan Jupyter Lab, ekstensi Visual Studio Code Jupyter, dan Azure Data Studio, dan sumber data yang didukung termasuk Azure Data Explorer, log Azure Monitor, dan Application Insights.

Dalam artikel ini, Anda akan mempelajari cara menggunakan kqlmagic di Jupyter Notebook untuk menyambungkan dan mengkueri data yang disimpan di Azure Data Explorer.

Prasyarat

  • Akun Microsoft atau identitas pengguna Microsoft Entra. Langganan Azure tidak diperlukan.
  • Jupyter Notebook terinstal di komputer lokal Anda. Jika tidak, gunakan Azure Data Studio.
  • Python 3.6. Untuk mengubah versi kernel Jupyter Notebook menjadi Python 3.6, pilih Kernel>Change Kernel>Python 3.6.

Menginstal kqlmagic

Setelah menginstal dan memuat ekstensi kqlmagic, Anda bisa menulis kueri KQL di buku catatan Anda. Jika kernel berhenti atau hasilnya tidak seperti yang diharapkan, muat ulang ekstensi kqlmagic.

  1. Untuk menginstal kqlmagic, jalankan perintah berikut:

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

  2. Untuk memuat ekstensi kqlmagic, jalankan perintah berikut:

    %reload_ext Kqlmagic

Terhubung ke klaster

Pilih tab untuk metode pilihan Anda untuk menyambungkan ke kluster Anda.

Catatan

Sebaiknya gunakan metode autentikasi Sertifikat jika memungkinkan.

Sertifikat Microsoft Entra harus disimpan dalam file yang dapat diakses dari buku catatan. File ini dapat dirujuk dalam string koneksi.

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

Tip

  • Untuk membuat parameter string koneksi, gunakan nilai yang tidak dikutip saat ditafsirkan sebagai ekspresi Python.
  • Untuk menyederhanakan proses mendapatkan kredensial, lihat opsi Koneksi ion.

Contoh koneksi kluster

Perintah berikut menggunakan metode kode Microsoft Entra untuk mengautentikasi ke database yang Samples dihosting pada help kluster. Untuk pengguna non-Microsoft Entra, ganti nama Microsoft.com penyewa dengan penyewa Microsoft Entra Anda.

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

Opsi koneksi

Untuk menyederhanakan proses mendapatkan kredensial, Anda bisa menambahkan salah satu bendera opsi berikut setelah string koneksi.

Opsi Deskripsi Contoh sintaks
try_azcli_login Coba dapatkan kredensial autentikasi dari Azure CLI. -try_azcli_login
try_azcli_login_subscription Coba dapatkan kredensial autentikasi dari Azure CLI berdasarkan langganan yang ditentukan. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Coba dapatkan kredensial autentikasi dari masuk akun Visual Studio Code Azure. -try_vscode_login
try_msi Coba dapatkan kredensial autentikasi dari titik akhir lokal MSI. Mengharapkan kamus dengan parameter MSI opsional: resource, ,/client_idobject_idmis_res_id/cloud_environment , . timeout -try_msi={"client_id":<id>}
try_token Autentikasi dengan token tertentu. Mengharapkan kamus dengan properti token Azure AD v1 atau v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

Contoh opsi koneksi

Salah satu opsi yang dijelaskan dalam tabel sebelumnya dapat ditambahkan setelah string koneksi. Contoh berikut menggunakan opsi masuk Azure CLI:

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

Tampilkan informasi koneksi

Untuk melihat semua koneksi yang ada, jalankan perintah berikut:

%kql --conn

Untuk memeriksa detail koneksi tertentu, jalankan perintah berikut:

%kql --conn <database-name>@<cluster-name>

Kueri dan visualisasi

Mengkueri data menggunakan operator render dan memvisualisasikan data menggunakan pustaka ploy.ly. Kueri dan visualisasi ini memberikan pengalaman terintegrasi yang menggunakan KQL asli. Kqlmagic mendukung sebagian besar bagan kecuali timepivot, , pivotchartdan ladderchart. Render didukung dengan semua atribut kecuali kind, , ysplitdan accumulate.

Mengkueri dan merender bagan pai

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take10
| render piechart title="My Pie Chart by State"

Kueri dan render bagan waktu

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

Catatan

Bagan ini interaktif. Pilih rentang waktu untuk memperbesar waktu tertentu.

Mengkustomisasi warna bagan

Jika Anda tidak menyukai palet warna default, kustomisasi bagan menggunakan opsi palet. Palet yang tersedia dapat ditemukan di sini: Pilih palet warna untuk hasil bagan kueri kqlmagic Anda

  1. Untuk daftar palet:

    %kql --palettes -popup_window

  2. cool Pilih palet warna dan render kueri lagi:

    %%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| render piechart title="My Pie Chart by State"

Membuat parameter kueri dengan Python

Kqlmagic memungkinkan pertukaran sederhana antara Bahasa Kueri Kusto dan Python. Untuk mempelajari lebih lanjut: Membuat parameter kueri kqlmagic Anda dengan Python

Menggunakan variabel Python dalam kueri KQL Anda

Anda bisa menggunakan nilai variabel Python dalam kueri Anda untuk memfilter data:

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

Mengonversi hasil kueri ke Pandas DataFrame

Anda dapat mengakses hasil kueri KQL di Pandas DataFrame. Akses hasil kueri terakhir yang dijalankan berdasarkan variabel _kql_raw_result_ dan dengan mudah mengonversi hasilnya menjadi Pandas DataFrame sebagai berikut:

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

Contoh

Dalam banyak skenario analitik, Anda mungkin ingin membuat notebook yang dapat digunakan kembali yang berisi banyak kueri dan memberi umpan hasil dari satu kueri ke dalam kueri berikutnya. Contoh di bawah ini menggunakan variabel statefilter Python untuk memfilter data.

  1. Jalankan kueri untuk menampilkan 10 status teratas dengan maksimum DamageProperty:

    %%kql
StormEvents
| summarize max(DamageProperty) by State
| order by max_DamageProperty desc
| take10

  2. Jalankan kueri untuk mengekstrak status teratas dan mengaturnya ke dalam variabel Python:

    df = _kql_raw_result_.to_dataframe()
statefilter =df.loc[0].State
statefilter

  3. Jalankan kueri menggunakan let pernyataan dan variabel Python:

    %%kql
let _state = statefilter;
StormEvents 
| where State in (_state)
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

  4. Jalankan perintah bantuan:

    %kql --help "help"

Tip

Untuk menerima informasi tentang semua konfigurasi yang tersedia, gunakan %config Kqlmagic. Untuk memecahkan masalah dan menangkap kesalahan Kusto, seperti masalah koneksi dan kueri yang salah, gunakan %config Kqlmagic.short_errors=False

Sampel notebook

Konten terkait