Plugin Python

Artikel
07/20/2022
6 menit untuk membaca

Plugin Python menjalankan fungsi yang ditentukan pengguna (UDF) menggunakan skrip Python. Skrip mendapat data tabular sebagai inputnya, dan menghasilkan output tabular. Runtime plugin dihosting dalam kotak pasir, yang berjalan pada node kluster.

Sintaks

T|evaluate [hint.distribution= (single | per_node)] python(output_schema,script [,script_parameters][,external_artifacts][,spill_to_disk])

Argumen

output_schema: type harfiah yang mendefinisikan skema output dari data tabular, dikembalikan oleh kode Phyton.
- Formatnya adalah: typeof(ColumnName:ColumnType[, ...]). Misalnya, typeof(col1:string, col2:long).
- Untuk memperluas skema input, gunakan sintaks berikut: typeof(*, col1:string, col2:long)
script: string harfiah yang merupakan skrip Python yang valid untuk dijalankan. Untuk menghasilkan string multibaris, lihat Tips penggunaan.
script_arguments: dynamic harfiah opsional. Ini adalah tas properti pasangan nama/nilai yang akan diteruskan ke skrip Python sebagai kamus kargs yang dicadangkan. Untuk informasi selengkapnya, lihat Variabel Phyton yang dicadangkan.
hint.distribution: Petunjuk opsional untuk eksekusi plugin yang akan didistribusikan di beberapa node kluster.
- Nilai defaultnya adalah single.
- single: Satu instans skrip akan berjalan di seluruh data kueri.
- per_node: Jika kueri sebelum blok Phyton didistribusikan, instans skrip akan berjalan pada setiap node, di data yang ada di dalamnya.
external_artifacts: dynamic harfiah opsional yang merupakan tas properti pasangan nama dan URL, untuk artefak yang dapat diakses dari penyimpanan cloud. Mereka dapat dibuat tersedia untuk skrip yang akan digunakan saat runtime.
- URL yang direferensikan dalam tas properti ini harus:
  - Termasuk dalam kebijakan panggilan kluster.
  - Berada di lokasi yang tersedia untuk umum, atau menyediakan kredensial yang diperlukan, seperti yang dijelaskan dalam string koneksi penyimpanan.
- Artefak dibuat tersedia untuk skrip yang akan dikonsumsi dari direktori sementara lokal, .\Temp. Nama-nama yang disediakan dalam tas properti digunakan sebagai nama file lokal. Lihat Contoh.
- Untuk informasi selengkapnya, lihat Menginstal paket untuk plugin Python.
spill_to_disk: boolean harfiah opsional yang menentukan metode alternatif untuk menserialisasi tabel input ke kotak pasir Python. Untuk serialisasi, tabel besar mengaturnya ke true untuk mempercepat serialisasi dan secara signifikan mengurangi konsumsi memori kotak pasir. Default-nya adalah false karena parameter ini eksperimental.

Variabel Python yang dicadangkan

Variabel berikut dicadangkan untuk interaksi antara Bahasa Kueri Kusto dan kode Phyton.

df: Data tabular input (nilai T di atas), sebagai DataFrame pandas.
kargs: Nilai argumen script_parameters, sebagai kamus Phyton.
result: DataFrame pandas yang dibuat oleh skrip Python, yang nilainya menjadi data tabular yang dikirim ke operator kueri Kusto yang mengikuti plugin.

Mengaktifkan plugin

Plugin dinonaktifkan secara default.
Untuk mengaktifkan plugin, lihat daftar prasyarat.
Aktifkan atau nonaktifkan plugin di portal Azure, di tab Konfigurasi kluster Anda.

Gambar kotak pasir Python

Gambar kotak pasir Python didasarkan pada distribusi Anaconda 5.2.0 dengan mesin Python 3.6. Lihat daftar paket Anaconda.

Catatan

Sebagian kecil paket mungkin tidak sesuai dengan batasan yang diberlakukan oleh kotak pasir tempat plugin dijalankan.
Gambar Python juga berisi paket ML umum: tensorflow, keras, torch, hdbscan, xgboost, dan paket berguna lainnya.
Plugin mengimpor numpy (sebagai np) &pandas (sebagai pd) secara default. Anda dapat mengimpor modul lain sesuai kebutuhan.

Menggunakan penyerapan dari kebijakan kueri dan pembaruan

Gunakan plugin dalam kueri yang:
- Ditentukan sebagai bagian dari kebijakan pembaruan, yang tabel sumbernya diserap untuk menggunakan penyerapan non-streaming.
- Jalankan sebagai bagian dari perintah yang menelan dari kueri, seperti .set-or-append. Dalam kedua kasus ini, verifikasi bahwa volume dan frekuensi penyerapan, serta kompleksitas dan sumber daya yang digunakan oleh logika Python, sejajar dengan batasan kotak pasir dan sumber daya kluster yang tersedia. Kegagalan melakukannya dapat mengakibatkan kesalahan pembatasan.
Anda tidak dapat menggunakan plugin dalam kueri yang didefinisikan sebagai bagian dari kebijakan pembaruan, yang tabel sumbernya diserap menggunakan penyerapan streaming.

Contoh

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

demo sinus.

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string), ```if 1:
    import os
    result = pd.DataFrame(columns=['File','Size'])
    sizes = []
    path = '.\\\\Temp'
    files = os.listdir(path)
    result['File']=files
    for file in files:
        sizes.append(os.path.getsize(path + '\\\\' + file))
    result['Size'] = sizes
    ```,
    external_artifacts = 
        dynamic({"this_is_my_first_file":"https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r",
                 "this_is_a_script":"https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py"})
)

File	Ukuran
this_is_a_script	120
this_is_my_first_file	105

Tips performa

Kurangi himpunan data input plugin ke jumlah minimum yang diperlukan (kolom/baris).
- Gunakan filter pada himpunan data sumber, jika memungkinkan, dengan bahasa kueri Kusto.
- Untuk membuat perhitungan pada subset kolom sumber, proyeksikan hanya kolom tersebut sebelum memanggil plugin.
Gunakan hint.distribution = per_node setiap kali logika dalam skrip Anda dapat didistribusikan.
- Anda juga dapat menggunakan operator partisi untuk mempartisi himpunan data input.
Gunakan bahasa kueri Kusto bila memungkinkan, untuk menerapkan logika skrip Python Anda.

Tips penggunaan

Untuk menghasilkan string multibaris yang berisi skrip Python pada Kusto.Explorer, salin skrip Python Anda dari editor Python favorit Anda (Jupyter, Visual Studio Code, PyCharm, dan sebagainya). Sekarang lakukan salah satu dari:
- Lampirkan skrip lengkap di antara baris yang berisi tiga backtick berurutan, misalnya:
```
python code
```
- Tekan F2 untuk membuka jendela Edit di Python. Tempelkan skrip ke jendela ini. PilihOK. Skrip akan dilengkapi dengan kuotasi dan baris baru, sehingga valid di Kusto, dan secara otomatis ditempelkan ke tab kueri.
- Tempelkan kode Python langsung ke tab kueri. Pilih garis-garis tersebut, dan tekan tombol pintas Ctrl+K, Ctrl+S, untuk melengkapinya seperti di atas. Untuk membalikkan, tekan tombol pintas Ctrl+K, Ctrl+M. Lihat daftar lengkap pintasan Editor Kueri.
Untuk menghindari konflik antara pemisah string Kusto dan harfiah string Phyton, gunakan:
- Gunakan karakter kuotasi tunggal (') untuk harfiah string Kusto dalam kueri Kusto
- Gunakan karakter kuotasi ganda (") untuk harfiah string Phyton dalam kueri Phyton

Gunakan externaldata operator untuk mendapatkan konten skrip yang telah Anda simpan di lokasi eksternal, seperti penyimpanan Azure Blob.

Contoh

let script = 
    externaldata(script:string)
    [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
    with(format = raw);
range x from 1 to 360 step 1
| evaluate python(
    typeof(*, fx:double),
    toscalar(script), 
    pack('gain', 100, 'cycles', 4))
| render linechart

Menginstal paket untuk plugin Python

Anda mungkin perlu menginstal paket sendiri, karena alasan berikut:

Paket ini bersifat pribadi dan milik Anda sendiri.
Paket ini bersifat publik tetapi tidak termasuk dalam gambar dasar plugin.

Instal paket sebagai berikut:

Prasyarat

Buat kontainer blob untuk menghosting paket, sebaiknya di tempat yang sama dengan kluster Anda. Misalnya, https://artifactswestus.blob.core.windows.net/python, dengan asumsi kluster Anda berada di US Barat.
Ubah kebijakan panggilan kluster untuk mengizinkan akses ke lokasi tersebut.
- Perubahan ini memerlukan izin AllDatabasesAdmin.
- Misalnya, untuk mengaktifkan akses ke blob yang berada di https://artifactswestus.blob.core.windows.net/python, jalankan perintah berikut:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
```

Memasang paket

Untuk paket publik di PyPi atau saluran lain, unduh paket dan dependensinya.
- Mengkompilasi file roda (*.whl), jika diperlukan.
- Dari jendela cmd di lingkungan Python lokal Anda, jalankan:
```
pip wheel [-w download-dir] package-name.
```
Buat file zip yang berisi paket yang diperlukan dan dependensinya.
- Untuk paket privat, zip folder paket dan folder dependensinya.
- Untuk paket publik, zip file yang diunduh pada langkah sebelumnya.
Catatan
- Pastikan untuk mengunduh paket yang kompatibel dengan mesin Python dari runtime kotak pasir (saat ini 3.6.5)
- Pastikan untuk zip file .whl sendiri, dan bukan folder induk mereka.
- Anda dapat melewati file .whl untuk paket yang sudah ada dengan versi yang sama di gambar kotak pasir dasar.
Unggah file zip ke blob di lokasi artefak (dari langkah 1).
Hubungi plugin python.
- Tentukan parameter external_artifacts dengan tas nama properti dan referensi ke file zip (URL blob, termasuk token SAS).
- Dalam kode python inline Anda, impor Zipackage dari sandbox_utils dan panggil metode install()-nya dengan nama file zip.

Contoh

Instal paket Faker yang menghasilkan data palsu.

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*), ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install("Faker.zip")
    from faker import Faker
    fake = Faker()
    result = df
    for i in range(df.shape[0]):
        result.loc[i, "Name"] = fake.name()
    ```,
    external_artifacts=pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

ID	Nama
1	Gary Tapia
2	Emma Evans
3	Ashley Bowen

Kemampuan ini tidak didukung di Azure Monitor