Utilitas sistem file NotebookUtils untuk Fabric

notebookutils.fs menyediakan utilitas untuk bekerja dengan berbagai sistem file, termasuk Azure Data Lake Storage (ADLS) Gen2 dan Azure Blob Storage. Pastikan Anda mengonfigurasi akses ke Azure Data Lake Storage Gen2 dan Azure Blob Storage dengan tepat.

Jalankan perintah berikut untuk mendapatkan gambaran umum metode yang tersedia:

notebookutils.fs.help()

Tabel berikut mencantumkan metode sistem file yang tersedia:

Metode Signature Deskripsi
ls ls(path: String): Array Mencantumkan konten direktori.
mkdirs mkdirs(path: String): Boolean Membuat direktori yang diberikan jika tidak ada, juga membuat direktori induk yang diperlukan.
cp cp(src: String, dest: String, recurse: Boolean = false): Boolean Menyalin file atau direktori, mungkin di seluruh sistem file.
fastcp fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean Menyalin file atau direktori melalui azcopy untuk performa yang lebih baik dengan volume data besar.
mv mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean Memindahkan file atau direktori, mungkin di seluruh sistem file.
put put(file: String, content: String, overwrite: Boolean = false): Boolean Menulis string yang ditentukan ke file, yang dikodekan dalam UTF-8.
head head(file: String, max_bytes: int = 1024 * 100): String Mengembalikan hingga byte pertama max_bytes dari file yang diberikan sebagai String yang dikodekan dalam UTF-8.
append append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean Menambahkan konten ke file.
rm rm(path: String, recurse: Boolean = false): Boolean Menghapus file atau direktori.
exists exists(path: String): Boolean Memeriksa apakah ada file atau direktori.
getProperties getProperties(path: String): Map Mendapatkan properti dari jalur yang diberikan. Hanya tersedia di notebook Python (tidak didukung di PySpark, Scala, atau R).

Nota

Semua metode sistem file tersedia di notebook Python, PySpark, Scala, dan R kecuali dinyatakan lain. Scala menggunakan nama parameter camelCase (misalnya, createPath alih-alih create_path, maxBytes bukan max_bytes).

Untuk operasi pemasangan dan pelepasan, lihat Pemasangan dan pelepasan file.

Nota

Ingatlah batasan dan pertimbangan berikut saat Anda bekerja dengan notebookutils.fs:

  • Perilaku jalur bervariasi menurut jenis buku catatan: Di buku catatan Spark, jalur relatif ditetapkan ke jalur ABFSS Lakehouse default. Di dalam notebook Python, jalur relatif berfungsi menuju direktori kerja sistem file lokal (/home/trusted-service-user/work).
  • Batasan tulis bersamaan: notebookutils.fs.append() dan notebookutils.fs.put() tidak mendukung penulisan bersamaan ke file yang sama karena kurangnya jaminan atomitas.
  • Tambahkan penundaan dalam perulangan: Saat menggunakan notebookutils.fs.append() dalam perulangan, tambahkan jeda 0,5-1 detik antara penulisan untuk menjaga integritas data.
  • Batasan pintasan OneLake: Untuk pintasan tipe S3/GCS, gunakan jalur yang dipasang alih-alih jalur ABFS untuk operasi cp() dan fastcp().
  • Batasan lintas wilayah: fastcp() tidak mendukung penyalinan file di OneLake di seluruh wilayah. Gunakan cp() sebagai gantinya.
  • Versi runtime: NotebookUtils dirancang untuk bekerja dengan Spark 3.4 (Runtime v1.2) ke atas.
  • cp() perilaku dalam buku catatan Python: Di notebook Python, cp() secara internal menggunakan mekanisme berbasis azcopy yang sama dengan fastcp(), sehingga kedua metode berperilaku identik.

NotebookUtils bekerja dengan sistem file dengan cara yang sama seperti API Spark. Contoh penggunaan notebookutils.fs.mkdirs() dan Lakehouse:

Penggunaan Jalur relatif dari akar HDFS Jalur absolut untuk sistem file ABFS Jalur absolut untuk sistem file lokal dalam simpul driver
Non-default Lakehouse Tidak didukung notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Default Lakehouse Direktori di bawah 'File' atau 'Tabel': notebookutils.fs.mkdirs("Files/<new_dir>") notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")

  • Untuk Lakehouse default, jalur file dipasang di notebook Anda dengan batas waktu cache file default 120 detik. Ini berarti bahwa file di-cache di folder sementara lokal notebook selama 120 detik, bahkan jika file dihapus dari Lakehouse. Jika Anda ingin mengubah aturan batas waktu, Anda dapat melepas pemasangan jalur file Lakehouse default dan memasangnya kembali dengan nilai fileCacheTimeout yang berbeda.

  • Untuk konfigurasi Lakehouse non-default, Anda dapat mengatur parameter yang sesuai fileCacheTimeout selama pemasangan jalur Lakehouse. Mengatur batas waktu ke 0 memastikan bahwa file terbaru diambil dari server Lakehouse.

Mencantumkan file

Untuk mencantumkan konten direktori, gunakan notebookutils.fs.ls('Your directory path'). Contohnya:

notebookutils.fs.ls("Files/tmp") # Relative path works with different base paths depending on notebook type
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # Absolute path using ABFS file system
notebookutils.fs.ls("file:/tmp")  # Full path of the local file system of driver node

notebookutils.fs.ls() API berulah secara berbeda saat menggunakan jalur relatif, tergantung pada jenis notebook.

  • Di notebook Spark: Jalur relatif adalah relatif terhadap jalur default ABFSS Lakehouse. Misalnya, notebookutils.fs.ls("Files") menunjuk ke direktori Files di Lakehouse default.

    Contohnya:

    notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")

  • Dalam buku catatan Python: Jalur relatif relatif terhadap direktori kerja sistem file lokal, yang secara default adalah /home/trusted-service-user/work. Oleh karena itu, Anda harus menggunakan jalur lengkap alih-alih jalur relatif notebookutils.fs.ls("/lakehouse/default/Files") untuk mengakses direktori Files di Lakehouse default.

    Contohnya:

    notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")

Lihat properti file

Gunakan notebookutils.fs.ls() untuk memeriksa properti file seperti nama file, jalur file, ukuran file, dan apakah item adalah file atau direktori.

files = notebookutils.fs.ls('Your directory path')
for file in files:
    print(file.name, file.isDir, file.isFile, file.path, file.size)

Gunakan f-string jika Anda ingin output yang lebih mudah dibaca:

files = notebookutils.fs.ls("Files/data")
for file in files:
    print(f"Name: {file.name}, Size: {file.size}, IsDir: {file.isDir}, Path: {file.path}")

Buat direktori baru

Buat direktori jika tidak ada, termasuk direktori induk yang diperlukan.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # Works with the default Lakehouse files using relative path 
notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # Based on ABFS file system 
notebookutils.fs.mkdirs("file:/<new_dir>")  # Based on local file system of driver node

Salin file

Salin file atau direktori di seluruh sistem file. Atur recurse=True untuk menyalin direktori secara rekursif.

notebookutils.fs.cp('source file or directory', 'destination file or directory', recurse=True)

Nota

Catatan buku catatan Python: Di notebook Python, cp() secara internal menggunakan mekanisme berbasis azcopy yang sama dengan fastcp(), memberikan performa yang efisien untuk kedua metode. Karena keterbatasan pintasan OneLake, ketika Anda perlu menggunakan notebookutils.fs.cp() untuk menyalin data dari pintasan jenis S3/GCS, disarankan untuk menggunakan jalur yang dipasang alih-alih jalur abfss.

Tip

Selalu periksa nilai pengembalian Boolean untuk memverifikasi apakah operasi berhasil. Gunakan notebookutils.fs.exists() untuk memverifikasi jalur sumber sebelum Anda memulai operasi salin.

Contoh berikut menunjukkan salinan lintas penyimpanan dari Lakehouse default ke akun ADLS Gen2:

notebookutils.fs.cp(
    "Files/local_data",
    "abfss://<container>@<account>.dfs.core.windows.net/remote_data",
    recurse=True
)

Salinan file yang berkinerja tinggi

Gunakan fastcp untuk operasi penyalinan yang lebih efisien, terutama dengan volume data besar. Parameter recurse secara default adalah True.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', recurse=True)

Tip

Gunakan fastcp() alih-alih cp() untuk transfer data besar. Metode ini fastcp menggunakan azcopy di balik layar, yang memberikan throughput yang jauh lebih baik untuk operasi file massal. Dalam notebook Python, keduanya cp() dan fastcp() menggunakan mekanisme dasar yang sama.

Ingatlah pertimbangan ini:

  • notebookutils.fs.fastcp() tidak mendukung penyalinan file di OneLake di seluruh wilayah. Dalam hal ini, Anda dapat menggunakan notebookutils.fs.cp() sebagai gantinya.
  • Karena keterbatasan pintasan OneLake, ketika Anda perlu menggunakan notebookutils.fs.fastcp() untuk menyalin data dari pintasan jenis S3/GCS, disarankan untuk menggunakan jalur yang dipasang alih-alih jalur abfss.

Pratinjau isi file

Mengembalikan hingga byte pertama max_bytes dari sebuah file sebagai string UTF-8.

notebookutils.fs.head('file path', max_bytes)

Tip

Untuk file besar, gunakan head() dengan nilai yang sesuai max_bytes untuk menghindari masalah memori. Nilai defaultnya adalah 100 KB (1024 * 100).

Contoh berikut membaca 1.000 byte pertama dari sebuah file:

content = notebookutils.fs.head("Files/data/sample.txt", 1000)
print(content)

Nota

Nilai default untuk max_bytes berbeda di seluruh bahasa: buku catatan Python dan Scala menggunakan 102400 (100 KB), sementara buku catatan R menggunakan 65535 (64 KB). Di Scala, parameter ini diberi nama maxBytes.

Pindahkan file

Memindahkan file atau direktori di seluruh sistem file.

notebookutils.fs.mv('source file or directory', 'destination directory', create_path=True, overwrite=True)

Penting

Nilai bawaan parameter create_path bervariasi menurut runtime.

  • Buku catatan Spark (PySpark, Scala, R): mengatur default ke False (false pada Scala, FALSE pada R). Direktori induk harus ada sebelum operasi pemindahan.
  • Buku catatan Python: nilai bawaan adalah True. Direktori induk dibuat secara otomatis jika tidak ada.

Untuk memastikan perilaku yang konsisten di seluruh runtime, atur create_path parameter secara eksplisit dalam kode Anda. Di Scala, parameter ini diberi nama createPath.

Gunakan parameter bernama jika Anda ingin kode yang lebih jelas:

notebookutils.fs.mv("Files/source.csv", "Files/new_folder/dest.csv", create_path=True, overwrite=True)

Tuliskan file

Tulis string UTF-8 ke file.

notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it already exists

Tambahkan konten ke file

Tambahkan string UTF-8 ke file.

notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it doesn't exist

Penting

notebookutils.fs.append() dan notebookutils.fs.put() tidak mendukung penulisan bersamaan ke file yang sama karena kurangnya jaminan atomitas.

Saat menggunakan notebookutils.fs.append API dalam perulangan for untuk menulis ke file yang sama, tambahkan jeda sekitar 0,5 hingga 1 detik di antara penulisan yang berulang. Rekomendasi ini karena operasi internal notebookutils.fs.append dari API flush bersifat asinkron, sehingga penundaan singkat membantu memastikan integritas data.

import time

for i in range(100):
    notebookutils.fs.append("Files/output/data.txt", f"Line {i}\n", True)
    time.sleep(0.5)  # Prevent data integrity issues

Hapus file atau direktori

Hapus file atau direktori. Atur recurse=True untuk menghapus direktori secara rekursif.

notebookutils.fs.rm('file path', recurse=True)

Periksa apakah ada file atau direktori

Periksa apakah file atau direktori ada di jalur yang ditentukan. Ini mengembalikan True jika jalur ada; jika tidak, maka mengembalikan False.

notebookutils.fs.exists("Files/data/input.csv")

Tip

Gunakan exists() sebelum melakukan operasi file untuk mencegah kesalahan. Misalnya, periksa apakah file sumber ada sebelum Anda mencoba menyalin atau memindahkannya.

if notebookutils.fs.exists("Files/data/input.csv"):
    notebookutils.fs.cp("Files/data/input.csv", "Files/backup/input.csv")
    print("File copied successfully.")
else:
    print("Source file not found.")

Mendapatkan atribut file

Dapatkan properti untuk jalur sebagai peta pasangan nama-nilai. Ini hanya didukung untuk jalur Azure Blob Storage.

Nota

Metode getProperties ini hanya tersedia di notebook Python. Ini tidak didukung di notebook Spark (PySpark, Scala, atau R).

Parameter:

Parameter Tipe Required Deskripsi
path string Yes Jalur ABFS ke file atau direktori.

Kembali: Kamus (peta) yang berisi properti metadata seperti ukuran file, waktu pembuatan, waktu modifikasi terakhir, dan jenis konten.

properties = notebookutils.fs.getProperties("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")
print(properties)

Konten terkait

  • Last updated on