Nástroje systému souborů NotebookUtils pro Fabric

notebookutils.fs poskytuje nástroje pro práci s různými systémy souborů, včetně Azure Data Lake Storage (ADLS) Gen2 a Azure Blob Storage. Ujistěte se, že správně nakonfigurujete přístup ke službě Azure Data Lake Storage Gen2 a Azure Blob Storage .

Pro přehled dostupných metod spusťte následující příkazy:

notebookutils.fs.help()

Následující tabulka uvádí dostupné metody systému souborů:

Metoda Signature Description
ls ls(path: String): Array Vypíše obsah adresáře.
mkdirs mkdirs(path: String): Boolean Vytvoří daný adresář, pokud neexistuje, a vytvoří také potřebné nadřazené adresáře.
cp cp(src: String, dest: String, recurse: Boolean = false): Boolean Zkopíruje soubor nebo adresář, případně napříč systémy souborů.
fastcp fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean Zkopíruje soubor nebo adresář přes azcopy, aby se zlepšil výkon s velkými objemy dat.
mv mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean Přesune soubor nebo adresář, případně napříč systémy souborů.
put put(file: String, content: String, overwrite: Boolean = false): Boolean Zapíše daný řetězec do souboru zakódovaného v kódování UTF-8.
head head(file: String, max_bytes: int = 1024 * 100): String Vrátí až první max_bytes bajty daného souboru jako řetězec kódovaný v UTF-8.
append append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean Připojí obsah k souboru.
rm rm(path: String, recurse: Boolean = false): Boolean Odebere soubor nebo adresář.
exists exists(path: String): Boolean Zkontroluje, jestli existuje soubor nebo adresář.
getProperties getProperties(path: String): Map Získá vlastnosti dané cesty. Dostupné jenom v poznámkových blocích Pythonu (nepodporuje se v PySpark, Scala nebo R).

Poznámka:

Všechny metody systému souborů jsou k dispozici v poznámkových blocích Python, PySpark, Scala a R, pokud není uvedeno jinak. Scala používá názvy parametrů camelCase (například createPath místo create_path). maxBytesmax_bytes

Informace o operacích připojení a odpojování najdete v tématu Připojení a odpojení souboru.

Poznámka:

Při práci s notebookutils.fs mějte na paměti následující omezení a aspekty:

  • Chování cesty se liší podle typu notebooku: V Spark notebookách se relativní cesty převedou na výchozí cestu ABFSS lakehouse. V poznámkových blocích Pythonu se relativní cesty řeší na pracovní adresář místního souborového systému (/home/trusted-service-user/work).
  • Omezení souběžného zápisu: notebookutils.fs.append() Souběžné notebookutils.fs.put() zápisy do stejného souboru nepodporují kvůli nedostatku záruk atomicity.
  • Zpoždění pro smyčku: Při použití notebookutils.fs.append() ve smyčce přidejte 0,5 až 1 sekundu pauzy mezi zápisy kvůli integritě dat.
  • Omezení klávesové zkratky OneLake: Pro klávesové zkratky typu S3/GCS používejte pro a cp() operace připojené cesty místo cest fastcp() ABFS.
  • Omezení mezi oblastmi: fastcp() Nepodporuje kopírování souborů ve OneLake napříč oblastmi. Místo toho použijte cp().
  • Verze modulu runtime: NotebookUtils je navržený tak, aby fungoval se Sparkem 3.4 (Runtime v1.2) a novějším.
  • cp() chování v poznámkových blocích Pythonu: V poznámkových blocích cp() Pythonu interně používá stejný mechanismus založený na azcopy jako fastcp(), takže se obě metody chovají stejně.

NotebookUtils pracuje se systémem souborů stejným způsobem jako rozhraní API Sparku. Vezměme notebookutils.fs.mkdirs() si například využití jezerního domu:

Využití Relativní cesta od kořenového adresáře HDFS Absolutní cesta pro systém souborů ABFS Absolutní cesta k místnímu systému souborů v uzlu ovladače
Nevýchozí lakehouse Nepodporováno notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Výchozí jezero Adresář v části Soubory nebo Tabulky: 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>")

  • U výchozího Lakehouse jsou cesty k souborům připojeny do vašeho notebooku s výchozím časovým limitem cache souborů 120 sekund. To znamená, že soubory jsou uloženy v lokální dočasné složce notebooku na 120 sekund, i když jsou odstraněny z jezerního domu. Pokud chcete změnit pravidlo timeoutu, můžete odpojit výchozí cesty souborů Lakehouse a připojit je znovu s jinou fileCacheTimeout hodnotou.

  • Pro nestandardní konfigurace jezerních domů můžete nastavit vhodný fileCacheTimeout parametr při montáži cest k jezerním domům. Nastavení timeoutu na 0 zajistí, že nejnovější soubor bude načten ze serveru Lakehouse.

Seznam souborů

Chcete-li zobrazit seznam obsahu adresáře, použijte notebookutils.fs.ls('Your directory path'). Například:

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

Rozhraní notebookutils.fs.ls() API se při použití relativní cesty může chovat odlišně, v závislosti na typu poznámkového bloku.

  • v poznámkovém bloku Sparku: Relativní cesta se odvíjí od výchozí cesty Lakehouse ABFSS. Například notebookutils.fs.ls("Files") odkazuje na adresář Files ve výchozím Lakehouse.

    Například:

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

  • V poznámkovém bloku Pythonu: Relativní cesta je relativní vzhledem k pracovnímu adresáři místního systému souborů, který je ve výchozím nastavení /home/trusted-service-user/work. Proto byste měli použít úplnou cestu místo relativní cesty notebookutils.fs.ls("/lakehouse/default/Files") pro přístup k adresáři Files ve výchozím Lakehouse.

    Například:

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

Zobrazení vlastností souboru

Slouží notebookutils.fs.ls() ke kontrole vlastností souboru, jako je název souboru, cesta k souboru, velikost souboru a jestli je položka souborem nebo adresářem.

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

Pokud chcete čitelnější výstup, použijte f-string:

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

Vytvoření nového adresáře

Vytvořte adresář, pokud neexistuje, včetně všech nezbytných nadřazených adresářů.

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

Kopírovat soubor

Zkopírujte soubor nebo adresář napříč systémy souborů. Nastavte recurse=True rekurzivní kopírování adresářů.

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

Poznámka:

Poznámkový blok Pythonu: V poznámkových blocíchcp() Pythonu interně používá stejný mechanismus založený na azcopy jako fastcp(), který poskytuje efektivní výkon pro obě metody. Vzhledem k omezením zkratky OneLake se doporučuje použít připojenou cestu místo cesty typu abfss, pokud potřebujete kopírovat data ze zkratky typu S3/GCS.

Návod

Vždy zkontrolujte boolean návratovou hodnotu a ověřte, zda operace byla úspěšná. Slouží notebookutils.fs.exists() k ověření zdrojové cesty před zahájením operace kopírování.

Následující příklad ukazuje kopii z výchozího jezera na ADLS Gen2 účet:

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

Efektivní kopírování souborů

Slouží fastcp k efektivnějším operacím kopírování, zejména u velkých objemů dat. Parametr recurse má výchozí hodnotu True.

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

Návod

Používejte fastcp() místo cp() velkých přenosů dat. Metoda fastcp používá azcopy pod pokličkou, což poskytuje výrazně lepší propustnost pro hromadné operace se soubory. V poznámkových blocích Pythonu používají jak cp(), tak fastcp() stejný základní mechanismus.

Mějte na paměti tyto aspekty:

  • notebookutils.fs.fastcp() nepodporuje kopírování souborů ve OneLake napříč oblastmi. V takovém případě můžete místo toho použít notebookutils.fs.cp() .
  • Vzhledem k omezením zkratky OneLake se doporučuje použít připojenou cestu místo cesty typu abfss, pokud potřebujete kopírovat data ze zkratky typu S3/GCS.

Náhled obsahu souboru

Vrátí až první max_bytes bajty souboru jako řetězec UTF-8.

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

Návod

U velkých souborů použijte head() s odpovídající hodnotou max_bytes, abyste se vyhnuli problémům s pamětí. Výchozí hodnota je 100 kB (1024 * 100).

Následující příklad přečte prvních 1 000 bajtů souboru:

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

Poznámka:

Výchozí hodnota pro max_bytes se liší podle jazyka: Poznámkové bloky Python a Scala používají 102400 (100 KB), zatímco poznámkové bloky pro R používají 65535 (64 KB). V jazyce Scala má tento parametr název maxBytes.

Přesunout soubor

Přesuňte soubor nebo adresář mezi systémy souborů.

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

Důležité

Výchozí hodnota parametru create_path se mění v závislosti na modulu runtime.

  • Poznámkové bloky Sparku (PySpark, Scala, R): výchozí hodnota False je (false v jazyce Scala, FALSE v R). Nadřazený adresář musí existovat před operací přesunutí.
  • Poznámkové bloky Pythonu: výchozí hodnota je True. Nadřazený adresář se vytvoří automaticky, pokud neexistuje.

Pokud chcete zajistit konzistentní chování napříč moduly runtime, explicitně nastavte create_path parametr v kódu. V jazyce Scala má tento parametr název createPath.

Pokud chcete jasnější kód, použijte pojmenované parametry:

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

Zápis souboru

Zapište řetězec UTF-8 do souboru.

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

Připojení obsahu k souboru

Připojte řetězec UTF-8 k souboru.

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

Důležité

notebookutils.fs.append() a notebookutils.fs.put() nepodporuje souběžné zápisy do stejného souboru kvůli nedostatku záruk atomicity.

Při použití notebookutils.fs.append rozhraní API ve for smyčce pro zápis do stejného souboru přidejte mezi opakované zápisy pauzu přibližně 0,5 až 1 sekundu. Toto doporučení je proto, že interní operace notebookutils.fs.append rozhraní API flush je asynchronní, takže krátká prodleva pomáhá zajistit integritu dat.

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

Odstranění souboru nebo adresáře

Odeberte soubor nebo adresář. Nastavte recurse=True na rekurzivní odebrání adresářů.

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

Kontrola, jestli soubor nebo adresář existuje

Zkontrolujte, jestli v zadané cestě existuje soubor nebo adresář. Vrátí True , pokud cesta existuje; v opačném případě vrátí False.

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

Návod

Před provedením operací se soubory používejte exists() , abyste zabránili chybám. Než se například pokusíte zkopírovat nebo přesunout zdrojový soubor, zkontrolujte, jestli existuje zdrojový soubor.

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

Získání vlastností souboru

Získejte vlastnosti pro cestu ve formě mapy párů název-hodnota. Podporuje se pouze pro cesty ke službě Azure Blob Storage.

Poznámka:

Tato getProperties metoda je dostupná jenom v poznámkových blocích Pythonu. Nepodporuje se v poznámkových blocích Spark (PySpark, Scala nebo R).

Parametry:

Parameter Typ Povinné Description
path String Ano Cesta ABFS k souboru nebo adresáři.

Vrátí: Slovník (mapa) obsahující vlastnosti metadat, jako je velikost souboru, čas vytvoření, čas poslední změny a typ obsahu.

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

Související obsah

  • Last updated on