Fabric için NotebookUtils dosya sistemi yardımcı programları

notebookutils.fs Azure Data Lake Storage (ADLS) 2. Nesil ve Azure Blob Depolama gibi çeşitli dosya sistemleriyle çalışmaya yönelik yardımcı programlar sağlar. Azure Data Lake Storage 2. Nesil ve Azure Blob Depolama erişimini uygun şekilde yapılandırdığınızdan emin olun.

Kullanılabilir yöntemlere genel bakış için aşağıdaki komutları çalıştırın:

notebookutils.fs.help()

Aşağıdaki tabloda kullanılabilir dosya sistemi yöntemleri listelemektedir:

Yöntem Signature Açıklama
ls ls(path: String): Array Bir dizinin içeriğini listeler.
mkdirs mkdirs(path: String): Boolean Mevcut değilse verilen dizini oluşturur ve ayrıca gerekli üst dizinleri oluşturur.
cp cp(src: String, dest: String, recurse: Boolean = false): Boolean Büyük olasılıkla dosya sistemleri arasında bir dosya veya dizin kopyalar.
fastcp fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean Büyük veri birimleriyle daha iyi performans için azcopy aracılığıyla bir dosya veya dizin kopyalar.
mv mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean Bir dosyayı veya dizini büyük olasılıkla dosya sistemleri arasında taşır.
put put(file: String, content: String, overwrite: Boolean = false): Boolean Verilen dizeyi UTF-8 ile kodlanmış bir dosyaya yazar.
head head(file: String, max_bytes: int = 1024 * 100): String Verilen dosyanın ilk max_bytes baytlarına kadar UTF-8'de kodlanmış bir Dize olarak döndürür.
append append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean İçeriği bir dosyaya ekler.
rm rm(path: String, recurse: Boolean = false): Boolean Bir dosyayı veya dizini kaldırır.
exists exists(path: String): Boolean Bir dosya veya dizin olup olmadığını denetler.
getProperties getProperties(path: String): Map Verilen yolun özelliklerini alır. Yalnızca Python not defterlerinde kullanılabilir (PySpark, Scala veya R'de desteklenmez).

Uyarı

Aksi belirtilmediği sürece tüm dosya sistemi yöntemleri Python, PySpark, Scala ve R not defterlerinde kullanılabilir. Scala, camelCase parametre adlarını kullanır (örneğin, createPath yerine create_pathmaxBytesyerine max_bytes ).

Bağlama ve çıkarma işlemleri için bkz. Dosya bağlama ve çıkarma.

Uyarı

ile notebookutils.fsçalışırken aşağıdaki kısıtlamaları ve dikkate alınacak noktaları göz önünde bulundurun:

  • Yol davranışı not defteri türüne göre değişir: Spark not defterlerinde göreli yollar varsayılan Lakehouse ABFSS yoluna çözümlenmektedir. Python not defterlerinde göreli yollar yerel dosya sistemi çalışma dizinine (/home/trusted-service-user/work ) çözümür.
  • Eşzamanlı yazma sınırlamaları: notebookutils.fs.append() ve notebookutils.fs.put() atomiklik garantilerinin olmaması nedeniyle aynı dosyaya eşzamanlı yazmaları desteklemez.
  • Ekleme döngüsü gecikmesi: Döngüleri kullanırken notebookutils.fs.append() , veri bütünlüğü için yazma işlemleri arasına 0,5-1 saniyelik uyku ekleyin.
  • OneLake kısayol sınırlamaları: S3/GCS türü kısayolları için, cp() ve fastcp() işlemlerinde ABFS yolları yerine bağlı yolları kullanın.
  • Bölgeler arası sınırlamalar: fastcp() OneLake'teki dosyaların bölgeler arasında kopyalanmasını desteklemez. Bunun yerine cp() kullanın.
  • Çalışma zamanı sürümü: NotebookUtils, Spark 3.4 (Runtime v1.2) ve üzeri sürümlerle çalışacak şekilde tasarlanmıştır.
  • cp() davranışı Python not defterlerinde: cp(), dahili olarak fastcp() ile aynı azcopy tabanlı mekanizmayı kullanır, böylece her iki yöntem de aynı şekilde davranır.

NotebookUtils, dosya sistemiyle Spark API'leriyle aynı şekilde çalışır. Örneğin, notebookutils.fs.mkdirs() ve Lakehouse kullanımını ele alalım:

Kullanım HDFS kök dizininden göreli yol ABFS dosya sistemi için mutlak yol Sürücü düğümünde yer alan yerel dosya sistemi için mutlak yol
Varsayılan olmayan Lakehouse Desteklenmiyor notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Varsayılan Lakehouse 'Dosyalar' veya 'Tablolar' altındaki dizin: 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>")

  • Varsayılan Lakehouse için, dosya yolları not defterinize 120 saniyelik varsayılan dosya önbelleği zaman aşımı ile bağlanır. Bu, dosyaların Lakehouse'dan kaldırılsalar bile not defterinin yerel geçici klasöründe 120 saniye boyunca önbelleğe alındığı anlamına gelir. Zaman aşımı kuralını değiştirmek istiyorsanız, varsayılan Lakehouse dosya yollarını kaldırarak ve farklı bir fileCacheTimeout değeriyle yeniden bağlayarak bunu yapabilirsiniz.

  • Varsayılan olmayan Lakehouse yapılandırmaları için, Lakehouse yollarının montajı sırasında uygun fileCacheTimeout parametreyi ayarlayabilirsiniz. Zaman aşımının 0 olarak ayarlanması, en son dosyanın Lakehouse sunucusundan getirildiğinden emin olur.

Dosyaları listeleme

Bir dizinin içeriğini listelemek için kullanın notebookutils.fs.ls('Your directory path'). Örneğin:

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, not defterinin türüne bağlı olarak göreli yol kullanırken farklı davranır.

  • Spark defteri: Göreceli yol, varsayılan Lakehouse'un ABFSS yoluna göre ayarlanmıştır. Örneğin, notebookutils.fs.ls("Files") varsayılan Lakehouse'da Files dizinine işaret eder.

    Örneğin:

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

  • Python not defterinde: Göreli yol, yerel dosya sisteminin çalışma dizinine göredir ve varsayılan olarak olur /home/trusted-service-user/work. Bu nedenle, varsayılan Lakehouse'daki notebookutils.fs.ls("/lakehouse/default/Files") dizinine erişmek için göreli yol Files yerine tam yolu kullanmanız gerekir.

    Örneğin:

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

Dosya özelliklerini görüntüleme

Dosya adı, dosya yolu, dosya boyutu ve bir öğenin dosya veya dizin olup olmadığı gibi dosya özelliklerini incelemek için kullanın notebookutils.fs.ls() .

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

Daha okunabilir bir çıkış istiyorsanız f dizelerini kullanın:

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

Yeni dizin oluşturma

Gerekli üst dizinler de dahil olmak üzere yoksa bir dizin oluşturun.

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

Dosyayı kopyalama

Dosya sistemleri arasında bir dosya veya dizin kopyalayın. Dizinleri özyinelemeli olarak kopyalamak için ayarlayın recurse=True .

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

Uyarı

Python not defteri notu: Python not defterlerinde cp() dahili olarak fastcp() ile aynı azcopy tabanlı mekanizmayı kullanır ve her iki yöntem için de verimli performans sağlar. OneLake kısayolunun sınırlamaları nedeniyle, S3/GCS türü kısayolundan veri kopyalamak için kullanmanız gerektiğinde, abfss yolu yerine bağlı bir yol kullanmanız önerilir.

Tavsiye

İşlemin başarılı olup olmadığını doğrulamak için her zaman Boole dönüş değerini denetleyin. Kopyalama işlemini başlatmadan önce kaynak yolu doğrulamak için kullanın notebookutils.fs.exists() .

Aşağıdaki örnekte, varsayılan Lakehouse'dan ADLS 2. Nesil hesabına çapraz depolama kopyası gösterilmektedir:

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

Verimli kopyalama dosyası

Özellikle büyük veri hacimlerinde daha verimli kopyalama işlemleri için kullanın fastcp . recurse parametresi varsayılan olarak değeridirTrue.

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

Tavsiye

Büyük veri aktarımları fastcp() yerine kullanıncp(). fastcp yöntemi, toplu dosya işlemleri için önemli ölçüde daha iyi aktarım hızı sağlayan arka planda azcopy kullanır. Python not defterlerinde hem cp() hem de fastcp() aynı temel mekanizmayı kullanır.

Şu noktaları göz önünde bulundurun:

  • notebookutils.fs.fastcp() , OneLake'teki dosyaların bölgeler arasında kopyalanmasını desteklemez. Bu durumda, bunun yerine kullanabilirsiniz notebookutils.fs.cp() .
  • OneLake kısayolunun sınırlamaları nedeniyle, S3/GCS türü kısayolundan veri kopyalamak için kullanmanız gerektiğinde, abfss yolu yerine bağlı bir yol kullanmanız önerilir.

Dosya içeriğini önizleme

Dosyanın ilk max_bytes baytlarına UTF-8 dizesi olarak geri dönün.

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

Tavsiye

Büyük dosyalar için, bellek sorunlarını önlemek amacıyla head()'ü uygun bir max_bytes değeriyle kullanın. Varsayılan değer 100 KB'tır (1024 * 100).

Aşağıdaki örnek bir dosyanın ilk 1.000 baytını okur:

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

Uyarı

için max_bytes varsayılan değer farklı dillerde farklılık gösterir: Python ve Scala not defterleri 102400 (100 KB), R not defterleri ise (64 KB) kullanır 65535 . Scala'da bu parametre olarak adlandırılır maxBytes.

Dosyayı taşıma

Bir dosyayı veya dizini dosya sistemleri arasında taşıma.

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

Önemli

Parametre varsayılanı create_path çalışma zamanına göre değişir:

  • Spark not defterleri (PySpark, Scala, R): varsayılan olarak False (false Scala'da, FALSE R'de). Taşıma işleminden önce üst dizin mevcut olmalıdır.
  • Python not defterleri: varsayılan olarak True. Ana dizin yoksa otomatik olarak oluşturulur.

Çalışma zamanları arasında tutarlı bir davranış sağlamak için, parametresini create_path kodunuzda açıkça ayarlayın. Scala'da bu parametre olarak adlandırılır createPath.

Daha net bir kod istiyorsanız adlandırılmış parametreleri kullanın:

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

Dosya yazma

Dosyaya UTF-8 dizesi yazın.

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

Dosyaya içerik ekleme

Dosyaya UTF-8 dizesi ekleyin.

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

Önemli

notebookutils.fs.append() ve notebookutils.fs.put() bölünmezlik garantilerinin olmaması nedeniyle aynı dosyaya eşzamanlı yazmayı desteklemez.

API'yi aynı dosyaya yazmak için bir notebookutils.fs.append döngüsünde kullanırken, yinelenen yazma işlemleri arasında yaklaşık 0,5 ila 1 saniyelik bir for komutu ekleyin. Bu önerinin nedeni, notebookutils.fs.append API'sinin iç flush işleminin zaman uyumsuz olmasıdır, bu nedenle kısa bir gecikme veri bütünlüğünü sağlamaya yardımcı olur.

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

Dosya veya dizin silme

Bir dosyayı veya dizini kaldırın. Dizinleri özyinelemeli olarak kaldırmak için ayarlayın recurse=True .

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

Dosya veya dizin olup olmadığını denetleme

Belirtilen yolda bir dosya veya dizin olup olmadığını denetleyin. Yol varsa döndürür True ; aksi takdirde döndürür False.

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

Tavsiye

Hataları önlemek için dosya işlemlerini gerçekleştirmeden önce kullanın exists() . Örneğin, kopyalamaya veya taşımaya çalışmadan önce kaynak dosyanın mevcut olup olmadığını denetleyin.

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.")

Dosya özelliklerini alma

Yol için özellikleri isim-değer çiftleri haritası olarak alın. Yalnızca Azure Blob Depolama yolları için desteklenir.

Uyarı

getProperties yöntemi yalnızca Python not defterlerinde kullanılabilir. Spark not defterlerinde (PySpark, Scala veya R) desteklenmez.

Parametreler:

Parametre Türü Zorunlu Açıklama
path Dize Evet Dosya veya dizinin ABFS yolu.

Döndürür: Dosya boyutu, oluşturma zamanı, son değiştirme zamanı ve içerik türü gibi meta veri özelliklerini içeren bir sözlük (harita).

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

İlgili içerik

  • Last updated on