Plugin Python

Beralih layanan menggunakan menu tarik-turun Versi. Pelajari selengkapnya tentang navigasi.
Berlaku untuk: ✅ Microsoft Fabric ✅ Azure Data Explorer

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= (single | per_nodehint.remote=auto)] | localpython(skrip , [,script_parameters] [,external_artifacts] [,spill_to_disk])

Pelajari selengkapnya tentang konvensi sintaksis.

Parameter

Nama	Tipe	Wajib	Deskripsi
output_schema	string	✔️	Literal 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 kotak pasir. Nilai defaultnya adalah single. single berarti satu instans skrip akan berjalan di seluruh data kueri dalam satu kotak pasir. per_node berarti bahwa jika kueri sebelum blok Python didistribusikan ke partisi, setiap partisi akan berjalan di kotak pasirnya sendiri secara paralel.
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 menjalankan 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 OneLake. 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 (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. 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 panda 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 yaitu:
  • Didefinisikan sebagai bagian dari kebijakan pembaruan, yang tabel sumbernya diserap oleh penyerapan antrean.
  • 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_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 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 di antara baris yang berisi tiga backtick berturut-turut. Contohnya:

  ```
python code
```

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

Contoh membaca data eksternal skrip Python

    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 OneLake dapat disediakan untuk skrip dan digunakan saat runtime.

Artefak tersedia agar skrip dibaca 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-artfacts. Perintah ini menghapus file yang di-cache dan memastikan bahwa kueri berikutnya berjalan dengan versi terbaru artefak.

Menginstal paket untuk plugin Python

Instal paket sebagai berikut:

Prasyarat

• Buat lakehouse untuk menghosting paket, sebaiknya di ruang kerja yang sama dengan eventhouse Anda.

Memasang paket

1. 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.
   

2. 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 kotak pasir (saat ini 3.10.8 atau 3.11.7 di Windows)
   • 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.

3. Unggah file zip ke lakehouse.

4. Salin URL OneLake (dari properti file zip)

5. Hubungi plugin python.

   • external_artifacts Tentukan parameter dengan tas properti dengan nama lokal dan URL OneLake dari file zip.
   • Dalam kode python sebaris Anda, impor Zipackage dari sandbox_utils dan panggil metodenya install() dengan nama file ZIP.

Contoh menggunakan artefak eksternal

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://msit-onelake.dfs.fabric.microsoft.com/MSIT_DEMO_WS/MSIT_DEMO_LH.Lakehouse/Files/Faker.zip;impersonate'))

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.