Plugin Python
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)] [hint.remote= (auto | local)] python(skripoutput_schema, [,script_parameters] [,external_artifacts][,spill_to_disk])
Pelajari selengkapnya tentang konvensi sintaksis.
Parameter
| Nama | Jenis | Diperlukan | Deskripsi |
|---|---|---|---|
| output_schema | string |
✔️ | Harfiah type yang menentukan skema output data tabular, dikembalikan oleh kode Python. Formatnya adalah: typeof(ColumnName:ColumnType[, ...]). Misalnya, typeof(col1:string, col2:long). Untuk memperpanjang skema input, gunakan sintaksis berikut: typeof(*, col1:string, col2:long). |
| skrip | string |
✔️ | Skrip Python yang valid untuk dijalankan. Untuk menghasilkan string multibaris, lihat Tips penggunaan. |
| script_parameters | dynamic |
Tas properti pasangan nilai nama yang akan diteruskan ke skrip Python sebagai kamus yang dipesan kargs . Untuk informasi selengkapnya, lihat Variabel Phyton yang dicadangkan. |
|
| hint.distribution | string |
Petunjuk untuk eksekusi plugin didistribusikan di beberapa node kluster. Nilai defaultnya adalah single. single berarti satu instans skrip akan berjalan di seluruh data kueri. per_node berarti bahwa jika kueri sebelum blok Python didistribusikan, instans skrip akan berjalan pada setiap simpul, pada data yang dikandungnya. |
|
| hint.remote | string |
Petunjuk ini hanya relevan untuk kueri lintas kluster. Nilai defaultnya adalah auto. auto berarti server memutuskan secara otomatis di kluster mana kode Python dijalankan. Mengatur nilai untuk local memaksa mengeksekusi kode Python pada kluster lokal. Gunakan jika plugin Python dinonaktifkan pada kluster jarak jauh. |
|
| external_artifacts | dynamic |
Tas properti pasangan nama dan URL untuk artefak yang dapat diakses dari penyimpanan cloud. Lihat selengkapnya di Menggunakan artefak eksternal. | |
| spill_to_disk | bool |
Menentukan metode alternatif untuk menserialisasikan tabel input ke kotak pasir Python. Untuk serialisasi, tabel besar mengaturnya ke true untuk mempercepat serialisasi dan secara signifikan mengurangi konsumsi memori kotak pasir. Defaultnya adalah true. |
Variabel Python yang dicadangkan
Variabel berikut dicadangkan untuk interaksi antara Bahasa Kueri Kusto dan kode Phyton.
df: Data tabular input (nilaiTdi atas), sebagai DataFramepandas.kargs: Nilai argumen script_parameters, sebagai kamus Phyton.result: DataFramepandasyang dibuat oleh skrip Python, yang nilainya menjadi data tabular yang dikirim ke operator kueri Kusto yang mengikuti plugin.
Mengaktifkan plugin
Plugin dinonaktifkan secara default. Sebelum memulai, tinjau daftar prasyarat. Untuk mengaktifkan plugin dan memilih versi gambar Python, lihat Mengaktifkan ekstensi bahasa pada kluster Anda.
Gambar kotak pasir Python
Untuk mengubah versi gambar Python, lihat Mengubah gambar ekstensi bahasa Python di kluster Anda.
Untuk melihat daftar paket untuk gambar Python yang berbeda, lihat Referensi paket Python.
Catatan
- Secara default, plugin mengimpor numpy sebagai np dan pandas sebagai pd. Secara opsional, Anda dapat mengimpor modul lain sesuai kebutuhan.
- Beberapa paket mungkin tidak kompatibel dengan batasan yang diberlakukan oleh kotak pasir tempat plugin dijalankan.
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.
- 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)
```
, bag_pack('gain', 100, 'cycles', 4) // dictionary of parameters
)
| render linechart
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_nodesetiap 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 di editor kueri Anda, salin skrip Python Anda dari editor Python favorit Anda (Jupyter, Visual Studio Code, PyCharm, dan sebagainya), tempelkan di editor kueri Anda, lalu sertakan skrip lengkap antar baris yang berisi tiga backtick berturut-turut. Contohnya:
```
python code
```Gunakan
externaldataoperator 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),
bag_pack('gain', 100, 'cycles', 4))
| render linechart
Menggunakan Artefak Eksternal
Artefak eksternal dari penyimpanan cloud dapat disediakan untuk skrip dan digunakan saat runtime.
URL yang dirujuk oleh properti artefak eksternal 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.
Catatan
Saat mengautentikasi artefak eksternal menggunakan Identitas Terkelola, SandboxArtifacts penggunaan harus ditentukan pada kebijakan identitas terkelola tingkat kluster.
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 mengenai mereferensikan paket eksternal, lihat Menginstal paket untuk plugin Python.
Menyegarkan cache artefak eksternal
File artefak eksternal yang digunakan dalam kueri di-cache pada kluster Anda. Jika Anda membuat pembaruan pada file Anda di penyimpanan cloud dan memerlukan sinkronisasi langsung dengan kluster Anda, Anda dapat menggunakan perintah .clear cluster cache external-artefacts. Perintah ini menghapus file yang di-cache dan memastikan bahwa kueri berikutnya berjalan dengan versi terbaru artefak.
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.
- Dari jendela cmd di lingkungan Windows 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 dan platform runtime sandbox (saat ini 3.6.5 di Windows)
- Pastikan untuk zip file
.whlsendiri, dan bukan folder induk mereka. - Anda dapat melewati file
.whluntuk 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_artifactsdengan tas nama properti dan referensi ke file zip (URL blob, termasuk token SAS). - Dalam kode python inline Anda, impor
Zipackagedarisandbox_utilsdan panggil metodeinstall()-nya dengan nama file zip.
- Tentukan parameter
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=bag_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 |
Konten terkait
Untuk contoh fungsi UDF lainnya yang menggunakan plugin Python, lihat pustaka Functions.
Plugin Python menjalankan fungsi yang ditentukan pengguna (UDF) menggunakan skrip Python. Skrip mendapat data tabular sebagai inputnya, dan menghasilkan output tabular.
Sintaks
T|evaluate [hint.distribution= (singleper_node | )] [hint.remote= (autolocal | )] python(skripoutput_schema, [,script_parameters] [,spill_to_disk])
Pelajari selengkapnya tentang konvensi sintaksis.
Parameter
| Nama | Jenis | Diperlukan | Deskripsi |
|---|---|---|---|
| output_schema | string |
✔️ | Harfiah type yang menentukan skema output data tabular, dikembalikan oleh kode Python. Formatnya adalah: typeof(ColumnName:ColumnType[, ...]). Misalnya, typeof(col1:string, col2:long). Untuk memperpanjang skema input, gunakan sintaksis berikut: typeof(*, col1:string, col2:long). |
| skrip | string |
✔️ | Skrip Python yang valid untuk dijalankan. Untuk menghasilkan string multibaris, lihat Tips penggunaan. |
| script_parameters | dynamic |
Tas properti pasangan nilai nama yang akan diteruskan ke skrip Python sebagai kamus yang dipesan kargs . Untuk informasi selengkapnya, lihat Variabel Phyton yang dicadangkan. |
|
| hint.distribution | string |
Petunjuk untuk eksekusi plugin didistribusikan di beberapa node kluster. Nilai defaultnya adalah single. single berarti satu instans skrip akan berjalan di seluruh data kueri. per_node berarti bahwa jika kueri sebelum blok Python didistribusikan, instans skrip akan berjalan pada setiap simpul, pada data yang dikandungnya. |
|
| hint.remote | string |
Petunjuk ini hanya relevan untuk kueri lintas kluster. Nilai defaultnya adalah auto. auto berarti server memutuskan secara otomatis di kluster mana kode Python dijalankan. Mengatur nilai untuk local memaksa mengeksekusi kode Python pada kluster lokal. Gunakan jika plugin Python dinonaktifkan pada kluster jarak jauh. |
|
| spill_to_disk | bool |
Menentukan metode alternatif untuk membuat serial tabel input ke kotak pasir Python. Untuk serialisasi, tabel besar mengaturnya ke true untuk mempercepat serialisasi dan secara signifikan mengurangi konsumsi memori kotak pasir. Defaultnya adalah true. |
Variabel Python yang dicadangkan
Variabel berikut dicadangkan untuk interaksi antara Bahasa Kueri Kusto dan kode Phyton.
df: Data tabular input (nilaiTdi atas), sebagai DataFramepandas.kargs: Nilai argumen script_parameters, sebagai kamus Phyton.result: DataFramepandasyang dibuat oleh skrip Python, yang nilainya menjadi data tabular yang dikirim ke operator kueri Kusto yang mengikuti plugin.
Mengaktifkan plugin
Plugin dinonaktifkan secara default. Sebelum memulai, aktifkan plugin Python di database KQL Anda.
Gambar kotak pasir Python
Untuk melihat daftar paket untuk gambar Python yang berbeda, lihat Referensi paket Python.
Catatan
- Secara default, plugin mengimpor numpy sebagai np dan pandas sebagai pd. Secara opsional, Anda dapat mengimpor modul lain sesuai kebutuhan.
- Beberapa paket mungkin tidak kompatibel dengan batasan yang diberlakukan oleh kotak pasir tempat plugin dijalankan.
Menggunakan penyerapan dari kueri dan memperbarui kebijakan
- 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.
- 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)
```
, bag_pack('gain', 100, 'cycles', 4) // dictionary of parameters
)
| render linechart
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_nodesetiap 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 di editor kueri Anda, salin skrip Python Anda dari editor Python favorit Anda (Jupyter, Visual Studio Code, PyCharm, dan sebagainya), tempelkan di editor kueri Anda, lalu sertakan skrip lengkap antar baris yang berisi tiga backtick berturut-turut. Contohnya:
```
python code
```Gunakan
externaldataoperator 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),
bag_pack('gain', 100, 'cycles', 4))
| render linechart
Konten terkait
Untuk contoh fungsi UDF lainnya yang menggunakan plugin Python, lihat pustaka Functions.
Kemampuan ini tidak didukung.
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk