Utilitas NotebookUtils User Data Function (UDF) untuk Fabric

Modul ini notebookutils.udf menyediakan utilitas untuk mengintegrasikan kode notebook dengan item Fungsi Data Pengguna (UDF). Anda dapat mengakses fungsi dari item UDF dalam ruang kerja yang sama atau di berbagai ruang kerja, lalu memanggil fungsi tersebut sesuai kebutuhan. Item UDF mempromosikan kegunaan ulang kode, pemeliharaan terpusat, dan kolaborasi tim.

Gunakan utilitas UDF untuk:

  • Pengambilan fungsi – Mengakses fungsi dari item UDF berdasarkan nama.
  • Akses lintas ruang kerja – Gunakan fungsi dari item UDF di ruang kerja lain.
  • Penemuan fungsi – Periksa fungsi yang tersedia dan tanda tangannya.
  • Pemanggilan fleksibel – Fungsi panggilan dengan parameter yang sesuai bahasa.

Nota

Anda memerlukan akses baca ke item UDF di ruang kerja target untuk mengambil fungsinya. Pengecualian dari fungsi UDF disebarkan ke buku catatan panggilan.

Tabel berikut mencantumkan metode UDF yang tersedia:

Metode Signature Deskripsi
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Mengambil semua fungsi dari item UDF berdasarkan ID artefak atau nama. Mengembalikan objek dengan atribut fungsi yang dapat dipanggil.

Objek yang dikembalikan mengekspos properti berikut:

Harta benda Tipe Deskripsi
functionDetails List Daftar kamus metadata fungsi. Setiap kamus mencakup: Name (nama fungsi), Description (deskripsi fungsi), Parameters (daftar definisi parameter), FunctionReturnType (jenis pengembalian), dan DataSourceConnections (koneksi sumber data yang digunakan).
itemDetails Kamus Kamus metadata item UDF dengan kunci: Id (ID artefak), Name (nama item), WorkspaceId (ID ruang kerja), dan CapacityId (ID kapasitas).
<functionName> Callable Setiap fungsi dalam item UDF menjadi metode yang dapat dipanggil pada objek yang dikembalikan. Gunakan myFunctions.functionName(...) untuk memanggil.

Tip

Ambil fungsi UDF sekali dan cache objek pembungkus. Hindari memanggil getFunctions() berulang kali dalam perulangan—sebaliknya cache hasilnya untuk meminimalkan overhead.

Mengambil fungsi dari UDF

Gunakan notebookutils.udf.getFunctions() untuk mendapatkan semua fungsi dari item UDF. Anda dapat secara opsional menentukan ID ruang kerja untuk akses lintas ruang kerja.

# Get functions from a UDF item in the current workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName')

# Get functions from a UDF item in another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

Memanggil fungsi

Setelah mengambil fungsi dari item UDF, panggil berdasarkan nama. Python mendukung parameter posisi dan parameter yang diberi nama. Contoh Scala dan R menggunakan parameter posisi.

# Positional parameters
myFunctions.functionName('value1', 'value2')

# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')

Nilai parameter standar

Fabric fungsi data pengguna mendukung nilai argumen default. Saat Anda memanggil fungsi yang diambil melalui notebookutils.udf.getFunctions, parameter apa pun yang memiliki default yang ditentukan dapat dihilangkan—runtime menggunakan default secara otomatis. Anda juga dapat menyediakan argumen bernama untuk mengesampingkan default tertentu sambil membiarkan yang lainnya pada defaultnya.

# Assume the UDF item defines a function like:
# def score_customer(customerId: str, startDate: datetime = "2025-01-01T00:00:00Z", isActive: bool = True, maxRecords: int = 100) -> dict
# The datetime defaults are specified as strings in the signature; the runtime parses them to datetime at invocation time.

# 1. Call without optional parameters — defaults are used for startDate, isActive, and maxRecords
result = myFunctions.scoreCustomer(customerId='C001')

# 2. Override one default via a named argument, keep the others at their defaults
result = myFunctions.scoreCustomer(customerId='C001', maxRecords=50)

# 3. Pass a date/time in ISO 8601 format for reliable parsing
result = myFunctions.scoreCustomer(customerId='C001', startDate='2025-12-31T23:59:59Z')

Jenis input default yang didukung

Jenis berikut didukung sebagai nilai parameter default:

Jenis default Notes
String String yang bisa diserialisasi ke JSON.
String tanggalwaktu Tentukan sebagai string dalam tanda tangan fungsi. Runtime menguraikannya pada datetime waktu pemanggilan. Gunakan format yang konsisten seperti ISO 8601 (misalnya, 2025-12-31T23:59:59Z).
Boolean True atau False.
Integer Nilai bilangan bulat apa pun.
Float Nilai floating-point apa pun.
List Harus dapat diserialisasikan sebagai JSON; gunakan None di dalam tanda tangan dan lakukan penetapan di dalam fungsi untuk menghindari risiko yang terkait dengan default yang dapat diubah.
Kamus Harus dapat diserialisasikan JSON; lebih suka None dalam tanda tangan dan tetapkan di dalam fungsi.
pandas DataFrame Disediakan sebagai objek JSON yang dikonversi SDK ke tipe pandas. Memerlukan fabric-user-data-functions versi 1.0.0 atau yang lebih baru.
Seri pandas Disediakan sebagai array objek JSON yang akan dikonversi oleh SDK menjadi tipe data Panda. Memerlukan fabric-user-data-functions versi 1.0.0 atau yang lebih baru.

Batasan dan panduan

Default harus dapat di-serialisasi dalam format JSON (set dan tuple tidak didukung). Untuk default daftar atau kamus, gunakan None dalam tanda tangan dan tetapkan default nyata di dalam fungsi untuk menghindari default yang dapat diubah bersama. Gunakan format ISO 8601 (misalnya, 2025-12-31T23:59:59Z) untuk default tanggalwaktu. Menggunakan pandas DataFrame atau Series sebagai default memerlukan fabric-user-data-functions versi 1.0.0 atau yang lebih baru.

Tampilkan detail

Anda dapat memeriksa metadata item UDF dan tanda tangan fungsi secara terprogram.

Tampilkan detail elemen UDF

display(myFunctions.itemDetails)

Tampilkan detail fungsi

display(myFunctions.functionDetails)

Tip

Selalu periksa functionDetails saat bekerja dengan item UDF baru. Ini membantu Anda memverifikasi fungsi yang tersedia dan jenis parameter yang diharapkan sebelum pemanggilan.

Penanganan kesalahan

Bungkus pemanggilan UDF dalam penanganan kesalahan yang sesuai bahasa untuk mengelola fungsi yang hilang atau jenis parameter yang tidak terduga dengan anggun. Selalu verifikasi bahwa fungsi ada di item UDF sebelum Anda memanggilnya.

import json

try:
    validators = notebookutils.udf.getFunctions('DataValidators')

    # Check if function exists before calling
    functions_info = json.loads(validators.functionDetails)
    function_names = [f['Name'] for f in functions_info]

    if 'validateSchema' in function_names:
        is_valid = validators.validateSchema(
            schema='sales_schema',
            data_path='Files/data/sales.csv'
        )
        print(f"Schema validation: {'passed' if is_valid else 'failed'}")
    else:
        print("validateSchema function not available in this UDF item")
        print(f"Available functions: {', '.join(function_names)}")

except AttributeError as e:
    print(f"Function not found: {e}")
except TypeError as e:
    print(f"Parameter type mismatch: {e}")
except Exception as e:
    print(f"Error invoking UDF: {e}")

Menggunakan fungsi UDF dalam alur data

Anda dapat menyusun fungsi UDF untuk membangun langkah-langkah ETL yang dapat digunakan kembali:

etl_functions = notebookutils.udf.getFunctions('ETLUtilities')

df = spark.read.csv('Files/raw/sales.csv', header=True)
cleaned_df = etl_functions.removeOutliers(df, columns=['amount'])
enriched_df = etl_functions.addCalculatedColumns(cleaned_df)
validated_df = etl_functions.validateAndFilter(enriched_df)

validated_df.write.mode('overwrite').parquet('Files/processed/sales.parquet')
print("ETL pipeline completed using UDF functions")

Penting

Pemanggilan UDF memiliki beban tambahan. Jika Anda memanggil fungsi yang sama dengan parameter yang sama berulang kali, pertimbangkan untuk menyimpan hasilnya. Hindari memanggil fungsi UDF dalam perulangan yang ketat jika memungkinkan.

Konten terkait

  • Last updated on