Utilitas pustaka variabel NotebookUtils untuk Fabric

Pustaka variabel membantu Anda menghindari nilai hardcoding dalam kode buku catatan. Daripada mengedit kode, Anda memperbarui nilai di pustaka dan mengambilnya saat runtime. Pola ini membantu Anda menggunakan kembali notebook di seluruh tim dan proyek dengan memusatkan konfigurasi.

Tabel berikut mencantumkan metode pustaka variabel yang tersedia:

Metode Signature Deskripsi
getLibrary getLibrary(variableLibraryName: String): VariableLibrary Mengambil objek pustaka variabel. Akses variabel sebagai properti pada objek yang dikembalikan, seperti library.variableName. Anda dapat menggunakan getVariable('name') atau sintaks kurung library['name'] untuk akses dinamis.
get get(variableReference: String): Any Mengambil nilai variabel tunggal dengan jalur referensinya dalam format $(/**/libraryName/variableName). Awalan /**/ diperlukan. Nilai secara otomatis ditik berdasarkan definisi variabel.

Tentukan variabel

Tentukan variabel di pustaka variabel Anda sebelum menggunakan notebookutils.variableLibrary. Anda dapat membuat dan mengelola pustaka variabel melalui UI Fabric.

Cuplikan layar daftar variabel di pustaka variabel.

Mengambil pustaka variabel

Gunakan getLibrary() untuk mengambil seluruh pustaka sebagai objek, lalu akses variabel sebagai properti. Gunakan sintaks kurung getVariable('name') atau library['name'] ketika Anda memerlukan akses dinamis.

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

# Property access
samplevl.test_int
samplevl.test_str

# Method access (useful for dynamic variable names)
samplevl.getVariable("test_int")

# Bracket access
samplevl["test_int"]

Contoh berikut menunjukkan cara membangun jalur file secara dinamis menggunakan nilai pustaka variabel:

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv"
df = spark.read.format("csv").option("header","true").load(file_path)

display(df)

Mengakses satu variabel menurut referensi

Gunakan metode get() dengan pola referensi $(/**/libraryName/variableName) untuk mengambil nilai satu variabel. Nilai secara otomatis ditik berdasarkan definisi variabel.

Penting

/**/ Awalan itu diperlukan dalam pola referensi. Pola lengkap harus $(/**/libraryName/variableName), di mana libraryName adalah nama item pustaka variabel yang tepat dan variableName merupakan variabel yang ditentukan dalam pustaka tersebut. Nama adalah peka terhadap huruf besar/kecil.

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

Jenis variabel yang didukung

Pustaka variabel mendukung jenis data berikut. Nilai secara otomatis diketik saat Anda mengambilnya—Anda tidak perlu mentransmisikannya secara eksplisit dalam banyak kasus.

Tipe Deskripsi Example
String Nilai teks. "my_connection_string"
Bilangan Bulat Angka bilangan bulat. 42
Boolean Boolean benar/salah. true
Number Angka desimal. 3.14
DateTime Nilai tanggal dan waktu dalam format ISO 8601. "2025-01-15T08:30:00Z"
Guid Pengidentifikasi unik global. "123e4567-e89b-12d3-a456-426614174000"
Referensi item Referensi ke item Fabric yang didukung. "workspace/item"

Konfigurasi khusus lingkungan

Pustaka variabel mendukung set nilai, yang memungkinkan Anda menentukan set nilai alternatif untuk variabel yang sama—misalnya, dev, test, dan prod. Setiap ruang kerja memiliki satu set nilai aktif dalam satu waktu, dan alur penyebaran dapat secara otomatis mengaktifkan set nilai yang sesuai untuk setiap tahap.

Pola ini menghilangkan kebutuhan akan perubahan kode saat Anda mempromosikan buku catatan di seluruh lingkungan:

# These values change based on the active value set (dev/test/prod)
app_config = notebookutils.variableLibrary.getLibrary("app_config")

api_endpoint = app_config.api_endpoint
batch_size = app_config.batch_size
debug_mode = app_config.debug_enabled

print(f"API Endpoint: {api_endpoint}")
print(f"Batch Size: {batch_size}")
print(f"Debug Mode: {debug_mode}")

if debug_mode:
    print("Running in debug mode")

Pertimbangan

Ingatlah pertimbangan ini:

  • notebookutils.variableLibrary API hanya mendukung akses ke pustaka variabel dalam ruang kerja yang sama. Akses lintas ruang kerja tidak didukung.
  • Anda tidak dapat mengambil pustaka variabel di seluruh ruang kerja di buku catatan anak selama eksekusi referensi.
  • Kode buku catatan mereferensikan variabel yang ditentukan dalam kumpulan nilai aktif pustaka variabel. Untuk menggunakan nilai yang berbeda, aktifkan kumpulan nilai yang berbeda di ruang kerja atau gunakan pipeline penyebaran untuk mengelola kumpulan nilai pada setiap lingkungan.
  • Service Principal (SPN) saat ini tidak didukung untuk variabel library utilities.
  • Perpustakaan variabel hanya bisa dibaca pada buku catatan. Lakukan perubahan melalui UI Fabric atau API.
  • Setiap pustaka mendukung hingga 1.000 variabel dan 1.000 set nilai, dengan maksimum 10.000 sel dan batas ukuran 1 MB.
  • Nama variabel dan pustaka sensitif terhadap huruf besar/kecil. Gunakan pencocokan nama yang tepat saat Anda mereferensikan variabel.

Tip

Gunakan alur penyebaran untuk mengaktifkan nilai yang sesuai secara otomatis yang ditetapkan untuk setiap tahap (dev, test, prod). Ini menghilangkan kebutuhan untuk beralih set nilai secara manual atau mengubah kode saat men-deploy buku catatan ke berbagai lingkungan.

Konten terkait

  • Last updated on