Nástroje súborového systému NotebookUtils pre Fabric

notebookutils.fs poskytuje nástroje na prácu s rôznymi súborovými systémami, vrátane Azure Data Lake Storage (ADLS) Gen2 a Azure Blob Storage. Nezabudnite nakonfigurovať prístup k službe Azure Data Lake Storage Gen2 a úložisku Azure Blob Storage správne.

Spustite nasledujúce príkazy a získajte prehľad dostupných metód:

notebookutils.fs.help()

Nasledujúca tabuľka uvádza dostupné metódy súborového systému:

Method	Podpis	Description
`ls`	`ls(path: String): Array`	Uvádza obsah adresára.
`mkdirs`	`mkdirs(path: String): Boolean`	Vytvorí daný adresár, ak neexistuje, a zároveň vytvorí všetky potrebné rodičovské adresáre.
`cp`	`cp(src: String, dest: String, recurse: Boolean = false): Boolean`	Kopíruje súbor alebo adresár, pravdepodobne naprieč súborovými systémami.
`fastcp`	`fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean`	Kopíruje súbor alebo adresár cez azcopy pre lepší výkon pri veľkých dátových objemoch.
`mv`	`mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean`	Presúva súbor alebo adresár, prípadne naprieč súborovými systémami.
`put`	`put(file: String, content: String, overwrite: Boolean = false): Boolean`	Zapíše daný reťazec do súboru zakódovaného v UTF-8.
`head`	`head(file: String, max_bytes: int = 1024 * 100): String`	Vráti až do prvých `max_bytes` bajtov daného súboru ako reťazec zakódovaný v UTF-8.
`append`	`append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean`	Pridáva obsah do súboru.
`rm`	`rm(path: String, recurse: Boolean = false): Boolean`	Odstráni súbor alebo adresár.
`exists`	`exists(path: String): Boolean`	Kontroluje, či existuje súbor alebo adresár.
`getProperties`	`getProperties(path: String): Map`	Získa vlastnosti danej cesty. Dostupné iba v Python zápisníkoch (nie je podporované v PySparku, Scale ani R).

Poznámka

Všetky metódy súborového systému sú dostupné v zápisníkoch Python, PySpark, Scala a R, pokiaľ nie je uvedené inak. Scala používa názvy parametrov camelCase (napríklad createPath namiesto create_path, namiesto maxBytes). max_bytes

Pre operácie primontovania a odmontovania pozri Súborové primontovanie a odmontovanie.

Poznámka

Majte na pamäti nasledujúce obmedzenia a úvahy pri práci s notebookutils.fs:

Správanie cesty sa líši podľa typu zápisníka: V Spark zápisníkoch sa relatívne cesty vyriešia na predvolenú ABFSS cestu Lakehouse. V Python zápisníkoch relatívne cesty vedú k lokálnemu pracovnému adresáru súborového systému (/home/trusted-service-user/work).
Obmedzenia súbežného zápisu: notebookutils.fs.append() a notebookutils.fs.put() nepodporujú súbežné zápisy do toho istého súboru kvôli nedostatku záruk atómovosti.
Oneskorenie slučky pripojenia: Pri použití notebookutils.fs.append() v slučkách pridajte medzi zápisy 0,5-1 sekundu spánku pre integritu dát.
Obmedzenia skratiek OneLake: Pre skratky typu S3/GCS použite namontované cesty namiesto ABFS ciest pre cp() a fastcp() operácie.
Obmedzenia medzi regiónmi: fastcp() nepodporuje kopírovanie súborov v OneLake medzi regiónmi. Použite namiesto toho cp() .
Runtime verzia: NotebookUtils je navrhnutý na spoluprácu so Spark 3.4 (Runtime v1.2) a vyšším.
cp() správanie v Python zápisníkoch: V Python zápisníkoch cp() sa interne používa rovnaký mechanizmus založený na azcopy, takže fastcp()obe metódy sa správajú rovnako.

Pomôcky pre notebookUtils fungujú so systémom súborov rovnakým spôsobom ako rozhrania Spark API. Vezmime notebookutils.fs.mkdirs() si napríklad využitie jazerného domu:

Použitie	Relatívna cesta z koreňa HDFS	Absolútna cesta k systému súborov ABFS	Absolútna cesta k lokálnemu systému súborov v uzli ovládača
Iný ako predvolený dom pri jazere	Nepodporované	`notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")`	`notebookutils.fs.mkdirs("file:/<new_dir>")`
Predvolený lakehouse	Adresár pod 'Súbory' alebo 'Tabuľky': `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>")`

Pre predvolený lakehouse sú cesty k súborom pripojené do vášho zápisníka s predvoleným časovým limitom vyrovnávacej pamäte súborov 120 sekúnd. To znamená, že súbory sú uložené v lokálnom dočasnom priečinku zápisníka na 120 sekúnd, aj keď sú z jazerného domu odstránené. Ak chcete zmeniť pravidlo timeoutu, môžete odmontovať predvolené cesty súborov Lakehouse a pripojiť ich znova s inou hodnotou fileCacheTimeout .
Pre neštandardné konfigurácie jazerných domov môžete nastaviť príslušný fileCacheTimeout parameter počas montáže ciestík k jazerným domom. Nastavenie timeoutu na 0 zabezpečí, že najnovší súbor sa načíta zo servera Lakehouse.

Zoznam súborov

Na zoznam obsahu adresára použite notebookutils.fs.ls('Your directory path'). Naprí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

notebookutils.fs.ls() API sa správa odlišne pri použití relatívnej cesty v závislosti od typu zápisníka.

v notebooku Spark: Relatívna cesta je relatívna k predvolenej ceste ABFSS lakehouse. Napríklad notebookutils.fs.ls("Files") odkazuje na Files adresár v predvolenom komplexe Lakehouse.

Napríklad:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
V Python zápisníku: Relatívna cesta je relatívna k pracovnému adresáru lokálneho súborového systému, ktorý je predvolene ./home/trusted-service-user/work Preto by ste mali namiesto relatívnej cesty použiť úplnú cestu notebookutils.fs.ls("/lakehouse/default/Files") na prístup k adresáru Files v predvolenom komplexe Lakehouse.

Napríklad:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Zobrazenie vlastností súboru

Použite na notebookutils.fs.ls() kontrolu vlastností súboru, ako je názov súboru, cesta k súboru, veľkosť súboru a či je položka súbor alebo adresár.

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

Použite f-struny, ak chcete čitateľnejší výstup:

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

Vytvorenie nového adresára

Vytvorte adresár, ak neexistuje, vrátane všetkých potrebných nadradených adresárov.

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írovať súbor

Skopírujte súbor alebo adresár naprieč súborovými systémami. Nastavte recurse=True kopírovanie adresárov rekurzívne.

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

Poznámka

Poznámka k Python notebooku: V Python notebookoch cp() sa interne používa rovnaký mechanizmus založený na azcopy, ktorý fastcp()poskytuje efektívny výkon pre obe metódy. Kvôli obmedzeniam skratky OneLake, keď potrebujete notebookutils.fs.cp() použiť kopírovanie dát zo skratky typu S3/GCS, odporúča sa použiť pripojenú cestu namiesto abfss cesty.

Prepitné

Vždy skontrolujte návratovú hodnotu Booleovskej hodnoty, aby ste overili, či operácia bola úspešná. Použite na notebookutils.fs.exists() overenie zdrojovej cesty pred začiatkom kopírovania.

Nasledujúci príklad ukazuje cross-storage kópiu z predvoleného lakehouse na ADLS Gen2 účet:

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

Výkonný kopírovací súbor

Použitie fastcp na efektívnejšie kopírovacie operácie, najmä pri veľkých objemoch dát. Parameter recurse je predvolene .True

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

Prepitné

Používajte fastcp() namiesto na cp() veľké prenosy dát. Metóda fastcp používa azcopy pod kapotou, čo poskytuje výrazne lepšiu priepustnosť pre hromadné operácie so súbormi. V Python notebookoch používajú oba cp()fastcp() a rovnaký základný mechanizmus.

Majte na pamäti tieto úvahy:

notebookutils.fs.fastcp() nepodporuje kopírovanie súborov v OneLake medzi regiónmi. V tomto prípade môžete namiesto toho použiť funkciu notebookutils.fs.cp() .
Kvôli obmedzeniam skratky OneLake, keď potrebujete notebookutils.fs.fastcp() použiť kopírovanie dát zo skratky typu S3/GCS, odporúča sa použiť pripojenú cestu namiesto abfss cesty.

Zobraziť ukážku obsahu súboru

Vráťte až do prvých max_bytes bajtov súboru ako reťazec UTF-8.

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

Prepitné

Pri veľkých súboroch používajte head() s vhodnou max_bytes hodnotou, aby ste predišli problémom s pamäťou. Predvolená hodnota je 100 KB (1024 * 100).

Nasledujúci príklad číta prvých 1 000 bajtov súboru:

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

Poznámka

Predvolená hodnota pre max_bytes sa líši medzi jazykmi: notebooky v Pythone a Scale používajú 102400 (100 KB), zatiaľ čo zápisníky v R používajú 65535 (64 KB). V Scale sa tento parameter nazýva maxBytes.

Presunúť súbor

Presúvajte súbor alebo adresár medzi súborovými systémami.

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

Dôležité

Predvolený create_path parameter sa líši podľa času behu:

Spark notebooky (PySpark, Scala, R): predvolene (Falsefalsev Scale, FALSE v R). Rodičovský adresár musí existovať pred operáciou presunu.
Python zápisníky: predvolene .True Rodičovský adresár sa automaticky vytvorí, ak neexistuje.

Aby ste zabezpečili konzistentné správanie naprieč runtime, explicitne nastavte create_path parameter vo svojom kóde. V Scale sa tento parameter nazýva createPath.

Ak chcete jasnejší kód, použite pomenované parametre:

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

Napísať súbor

Zapíšte reťazec UTF-8 do súboru.

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

Pripojenie obsahu k súboru

Pridajte reťazec UTF-8 do súboru.

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() nepodporujú súbežné písanie do toho istého súboru kvôli nedostatku záruk atómovosti.

Pri používaní notebookutils.fs.append API v slučke for na zápis do toho istého súboru pridajte sleep príkaz približne 0,5 až 1 sekundy medzi opakujúcimi sa zápismi. Toto odporúčanie je spôsobené tým, že notebookutils.fs.append interná operácia flush rozhrania API je asynchrónne, takže krátke oneskorenie pomáha zabezpečiť integritu údajov.

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

Odstránenie súboru alebo adresára

Odstráňte súbor alebo adresár. Nastavte recurse=True rekurzívne odstraňovanie adresárov.

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

Skontrolujte, či existuje súbor alebo adresár

Skontrolujte, či na určenej ceste existuje súbor alebo adresár. Vráti, True ak cesta existuje; inak vráti .False

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

Prepitné

Použite pred exists() vykonaním súborových operácií na prediexit chýb. Napríklad si skontrolujte, či existuje zdrojový súbor, skôr než sa ho pokúsite skopírovať alebo presunúť.

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ískajte vlastnosti súboru

Získajte vlastnosti pre cestu ako zobrazenie párov meno-hodnota. Je podporovaný iba pre Azure Blob Storage cesty.

Poznámka

Metóda getProperties je dostupná iba v Python zápisníkoch. Nie je podporovaný v Spark notebookoch (PySpark, Scala alebo R).

Parametre:

Parameter	Typ	Požaduje sa	Description
`path`	Povrázok	Áno	ABFS cesta k súboru alebo adresáru.

Výnosy: Slovník (mapa) obsahujúci vlastnosti metadát, ako sú veľkosť súboru, čas vytvorenia, čas poslednej úpravy a typ obsahu.

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

Pripomienky

Bola táto stránka užitočná?

Last updated on 2026-08-05

Nástroje súborového systému NotebookUtils pre Fabric

Zoznam súborov

Zobrazenie vlastností súboru

Vytvorenie nového adresára

Kopírovať súbor

Výkonný kopírovací súbor

Zobraziť ukážku obsahu súboru

Presunúť súbor

Napísať súbor

Pripojenie obsahu k súboru

Odstránenie súboru alebo adresára

Skontrolujte, či existuje súbor alebo adresár

Získajte vlastnosti súboru

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií