NotebookUtils memasang dan melepas pemasangan file untuk Fabric

NotebookUtils mendukung operasi pemasangan file dan pelepasan pemasangan melalui paket Microsoft Spark Utilities. Anda dapat menggunakan API mount, unmount, getMountPath(), dan mounts() untuk melampirkan penyimpanan jarak jauh (ADLS Gen2, Azure Blob Storage, OneLake) ke semua simpul kerja (simpul pengemudi dan simpul pekerja). Setelah titik pemasangan penyimpanan ada, gunakan API file lokal untuk mengakses data seolah-olah disimpan dalam sistem file lokal.

Operasi pemasangan sangat berguna ketika Anda:

  • Bekerja dengan pustaka yang mengharapkan jalur file lokal.
  • Perlu semantik sistem file yang konsisten di seluruh penyimpanan cloud.
  • Akses pintasan OneLake (S3/GCS) secara efisien.
  • Buat kode portabel yang berfungsi dengan beberapa backend penyimpanan.

Referensi API

Tabel berikut ini meringkas API pemasangan yang tersedia:

Metode Signature Deskripsi
mount mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean Memasang penyimpanan jarak jauh pada titik pemasangan yang ditentukan.
unmount unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean Melepas dan menghapus titik pemasangan.
mounts mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo] Mencantumkan semua titik pemasangan yang ada dengan detail.
getMountPath getMountPath(mountPoint: String, scope: String = ""): String Mendapatkan jalur sistem file lokal untuk titik pemasangan.

Metode autentikasi

Operasi pemasangan mendukung beberapa metode autentikasi. Pilih metode berdasarkan jenis penyimpanan dan persyaratan keamanan Anda.

Autentikasi token Microsoft Entra menggunakan identitas pelaksana notebook, baik pengguna atau perwakilan layanan. Ini tidak memerlukan kredensial eksplisit dalam panggilan pemasangan, yang menjadikannya opsi yang paling aman. Gunakan opsi ini untuk pemasangan Lakehouse dan penyimpanan ruang kerja Fabric.

# Mount using Microsoft Entra token (no credentials needed)
notebookutils.fs.mount(
    "abfss://mycontainer@mystorageaccount.dfs.core.windows.net",
    "/mydata"
)

Tip

Gunakan autentikasi token Microsoft Entra jika memungkinkan. Ini menghilangkan risiko paparan kredensial dan tidak memerlukan pengaturan tambahan untuk penyimpanan ruang kerja Fabric.

Kunci akun

Gunakan kunci akun saat akun penyimpanan tidak mendukung autentikasi Microsoft Entra, atau saat Anda mengakses penyimpanan eksternal atau pihak ketiga. Simpan kunci akun di Azure Key Vault dan ambil dengan notebookutils.credentials.getSecret API.

# Retrieve account key from Azure Key Vault
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"accountKey": accountKey}
)

Token tanda tangan akses bersama (SAS)

Gunakan token tanda tangan akses bersama (SAS) untuk akses terbatas waktu dan cakupan izin. Opsi ini berguna ketika Anda perlu memberikan akses sementara ke pihak eksternal. Simpan token SAS di Azure Key Vault.

# Retrieve SAS token from Azure Key Vault
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"sasToken": sasToken}
)

Penting

Untuk tujuan keamanan, hindari menyematkan kredensial langsung dalam kode. Rahasia apa pun yang ditampilkan dalam output notebook secara otomatis diredaksi. Untuk informasi selengkapnya, lihat Redaksi rahasia.

Memasang akun ADLS Gen2

Contoh berikut mengilustrasikan cara memasang Azure Data Lake Storage Gen2. Pemasangan Blob Storage dan Azure File Share berfungsi sama.

Contoh ini mengasumsikan bahwa Anda memiliki satu akun Data Lake Storage Gen2 bernama storegen2, yang memiliki kontainer bernama mycontainer yang ingin Anda pasang ke /uji dalam sesi Spark notebook Anda.

Cuplikan layar memperlihatkan tempat memilih kontainer untuk dipasang.

Untuk memasang kontainer yang disebut mycontainer, NotebookUtils terlebih dahulu perlu memeriksa apakah Anda memiliki izin untuk mengakses kontainer. Saat ini, Fabric mendukung tiga metode autentikasi untuk operasi pemasangan pemicu: Token Microsoft Entra (default), accountKey, dan sasToken.

Untuk alasan keamanan, simpan kunci akun atau token SAS di Azure Key Vault (seperti yang ditunjukkan cuplikan layar berikut). Lalu, Anda dapat mengambil kunci atau token tersebut menggunakan notebookutils.credentials.getSecret API. Untuk informasi selengkapnya tentang Azure Key Vault, lihat Tentang kunci akun penyimpanan terkelola Azure Key Vault.

Cuplikan layar memperlihatkan tempat rahasia disimpan di Azure Key Vault.

Kode sampel untuk metode accountKey :

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Kode sampel untuk sasToken:

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Parameter pengaitan/pemasangan

Anda dapat menyetel perilaku pemasangan dengan parameter opsional berikut di extraConfigs peta:

  • fileCacheTimeout: Blob di-cache di folder sementara lokal selama 120 detik secara default. Selama waktu ini, blobfuse tidak memeriksa apakah file sudah diperbarui. Anda dapat mengatur parameter ini untuk mengubah batas waktu default. Ketika beberapa klien memodifikasi file secara bersamaan, untuk menghindari inkonsistensi antara file lokal dan jarak jauh, persingkat waktu cache atau atur ke 0 untuk selalu mendapatkan file terbaru dari server.
  • batas waktu: Batas waktu operasi pemasangan adalah 30 detik secara default. Anda dapat mengatur parameter ini untuk mengubah batas waktu default. Ketika ada terlalu banyak pelaksana atau ketika waktu pemasangan habis, tingkatkan nilainya.

Anda dapat menggunakan parameter ini seperti ini:

notebookutils.fs.mount(
   "abfss://mycontainer@<accountname>.dfs.core.windows.net",
   "/test",
   {"fileCacheTimeout": 120, "timeout": 30}
)

Rekomendasi konfigurasi cache

Pilih nilai batas waktu cache berdasarkan pola akses Anda:

Skenario Direkomendasikan fileCacheTimeout Catatan
Banyak pembacaan, satu klien 120 (standar) Keseimbangan kinerja dan kesegaran yang baik.
Memoderasi akses multi-klien 30–60 Mengurangi risiko data kedaluarsa.
Beberapa klien memodifikasi file 0 Selalu mengambil yang terbaru dari server.
File jarang berubah 300+ Mengoptimalkan performa baca.

Pola tanpa-cache

Ketika beberapa klien memodifikasi file secara bersamaan, gunakan konfigurasi zero-cache untuk selalu mengambil versi terbaru dari server:

# For scenarios with multiple clients modifying files
# Use zero cache to always fetch the latest from the server
notebookutils.fs.mount(
    "abfss://shared@account.dfs.core.windows.net",
    "/shared_data",
    {"fileCacheTimeout": 0}
)

Nota

Tingkatkan parameter timeout saat memasang dengan banyak eksekutor atau saat Anda mengalami kesalahan batas waktu.

Memasang Lakehouse

Pemasangan Lakehouse hanya mendukung autentikasi token Microsoft Entra. Kode sampel untuk memasang Lakehouse ke /<mount_name>:

notebookutils.fs.mount( 
 "abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse", 
 "/<mount_name>"
)

Mengakses file di bawah titik pemasangan dengan menggunakan API notebookutils fs

Gunakan operasi pemasangan saat Anda ingin mengakses data di penyimpanan jarak jauh melalui API sistem file lokal. Anda juga dapat mengakses data yang terpasang dengan menggunakan notebookutils.fs API dengan path terpasang, tetapi format path-nya berbeda.

Asumsikan bahwa Anda memasang kontainer Data Lake Storage Gen2 mycontainer ke /test dengan menggunakan API mount. Saat Anda mengakses data dengan API sistem file lokal, format jalurnya seperti ini:

/synfs/notebook/{sessionId}/test/{filename}

Saat Anda ingin mengakses data dengan menggunakan notebookutils fs API, gunakan getMountPath() untuk mendapatkan jalur yang akurat:

path = notebookutils.fs.getMountPath("/test")

  • Daftarkan direktori.

    notebookutils.fs.ls(f"file://{notebookutils.fs.getMountPath('/test')}")

  • Membaca isi dari file.

    notebookutils.fs.head(f"file://{notebookutils.fs.getMountPath('/test')}/myFile.txt")

  • Membuat direktori.

    notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")

Mengakses file di bawah titik pemasangan melalui jalur lokal

Anda dapat membaca dan menulis file di titik pemasangan dengan menggunakan sistem file standar. Contoh Python berikut menunjukkan pola ini:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Periksa titik pemasangan yang ada

notebookutils.fs.mounts() Gunakan API untuk memeriksa semua info titik pemasangan yang ada:

notebookutils.fs.mounts()

Tip

Selalu periksa pemasangan yang ada dengan mounts() sebelum membuat titik pemasangan baru untuk menghindari konflik.

Periksa apakah sebuah mount sudah ada sebelum melakukan mount

existing_mounts = notebookutils.fs.mounts()
mount_point = "/mydata"

if any(m.mountPoint == mount_point for m in existing_mounts):
    print(f"Mount point {mount_point} already exists")
else:
    notebookutils.fs.mount(
        "abfss://container@account.dfs.core.windows.net",
        mount_point
    )
    print("Mount created successfully")

Melepas titik pemasangan

Gunakan kode berikut untuk melepas titik pemasangan Anda (/uji dalam contoh ini):

notebookutils.fs.unmount("/test")

Penting

Mekanisme pemutusan pemasangan tidak diterapkan secara otomatis. Ketika eksekusi aplikasi selesai, untuk melepas titik pemasangan dan melepaskan ruang disk, Anda perlu secara eksplisit memanggil API unmount dalam kode Anda. Jika tidak, titik pemasangan masih ada di simpul setelah aplikasi berjalan selesai.

Alur kerja pemasangan-pemrosesan-pembongkaran

Untuk pengelolaan sumber daya yang andal, bungkus operasi pemasangan dalam blok try/finally untuk memastikan pembersihan tetap terjadi bahkan jika terjadi kesalahan.

def process_with_mount(source_uri, mount_point):
    """Complete workflow: mount, process, unmount."""
    
    try:
        # Step 1: Check if already mounted
        existing = notebookutils.fs.mounts()
        if any(m.mountPoint == mount_point for m in existing):
            print(f"Already mounted at {mount_point}")
        else:
            notebookutils.fs.mount(source_uri, mount_point)
            print(f"Mounted {source_uri} at {mount_point}")
        
        # Step 2: Process data using local file system
        mount_path = notebookutils.fs.getMountPath(mount_point)
        
        with open(f"{mount_path}/data/input.txt", "r") as f:
            data = f.read()
        
        processed = data.upper()
        
        with open(f"{mount_path}/output/result.txt", "w") as f:
            f.write(processed)
        
        print("Processing complete")
        
    finally:
        # Step 3: Always unmount to release resources
        notebookutils.fs.unmount(mount_point)
        print(f"Unmounted {mount_point}")

process_with_mount(
    "abfss://mycontainer@mystorage.dfs.core.windows.net",
    "/temp_mount"
)

Batasan yang diketahui

  • Pemasangan perangkat adalah konfigurasi tingkat pekerjaan. mounts Gunakan API untuk memeriksa apakah titik pemasangan sudah ada atau tersedia.
  • Melepas pemasangan tidak terjadi secara otomatis. Setelah aplikasi selesai berjalan, panggil API unmount di dalam kode Anda untuk membebaskan ruang disk. Jika tidak, titik pemasangan tetap berada pada simpul setelah eksekusi aplikasi selesai.
  • Memasang akun penyimpanan ADLS Gen1 tidak didukung.

Konten terkait

  • Last updated on