Megosztás a következőn keresztül:

NotebookUtils fájlrendszeri segédprogramok a "Fabrichez"

notebookutils.fs Segédprogramokat biztosít a különböző fájlrendszerek, például az Azure Data Lake Storage (ADLS) Gen2 és az Azure Blob Storage használatához. Győződjön meg arról, hogy megfelelően konfigurálja az Azure Data Lake Storage Gen2 és az Azure Blob Storage elérését.

Futtassa az alábbi parancsokat az elérhető módszerek áttekintéséhez:

notebookutils.fs.help()

Az alábbi táblázat az elérhető fájlrendszer-metódusokat sorolja fel:

Módszer Signature Leírás
ls ls(path: String): Array Egy könyvtár tartalmát sorolja fel.
mkdirs mkdirs(path: String): Boolean Hozza létre a megadott könyvtárat, ha nem létezik, és hozzon létre minden szükséges szülőkönyvtárat is.
cp cp(src: String, dest: String, recurse: Boolean = false): Boolean Fájl vagy könyvtár másolása, esetleg fájlrendszerek között.
fastcp fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean Fájl vagy könyvtár másolása az azcopy használatával a nagyobb adatkötetek jobb teljesítménye érdekében.
mv mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean Áthelyez egy fájlt vagy könyvtárat, esetleg fájlrendszerek között.
put put(file: String, content: String, overwrite: Boolean = false): Boolean Az adott sztringet egy UTF-8 kóddal kódolt fájlba írja ki.
head head(file: String, max_bytes: int = 1024 * 100): String Visszaadja az adott fájl legfeljebb első max_bytes bájtját UTF-8-ban kódolt sztringként.
append append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean Hozzáfűzi a tartalmat egy fájlhoz.
rm rm(path: String, recurse: Boolean = false): Boolean Eltávolít egy fájlt vagy könyvtárat.
exists exists(path: String): Boolean Ellenőrzi, hogy létezik-e fájl vagy könyvtár.
getProperties getProperties(path: String): Map Lekéri az adott elérési út tulajdonságait. Csak Python-jegyzetfüzetekben érhető el (PySparkban, Scalában vagy R-ben nem támogatott).

Megjegyzés:

A Python, PySpark, Scala és R notebookokban minden fájlrendszer-metódus elérhető, kivéve, ha másként van feltüntetve. A Scala camelCase paraméterneveket használ (például createPathcreate_pathmaxBytes helyette max_bytes).

A csatlakoztatási és leválasztási műveletekről a Fájl csatlakoztatása és leválasztása című témakörben olvashat.

Megjegyzés:

A következő korlátozásokat és szempontokat tartsa szem előtt, amikor a következőkkel dolgozik notebookutils.fs:

  • Az elérési út viselkedése a jegyzetfüzet típusa szerint változik: A Spark-jegyzetfüzetekben a relatív elérési utak az alapértelmezett Lakehouse ABFSS-útvonalra vannak feloldva. Python-jegyzetfüzetekben a relatív elérési utak feloldódnak a helyi fájlrendszer munkakönyvtárához (/home/trusted-service-user/work).
  • Egyidejű írási korlátozások: notebookutils.fs.append() és notebookutils.fs.put() nem támogatják az egyidejű írásokat ugyanarra a fájlra az atomitási garanciák hiánya miatt.
  • Ciklus késleltetés hozzáadása: Ha notebookutils.fs.append() ciklusokban használja, adjon hozzá 0,5–1 másodperces várakozást az írások között az adatintegritás érdekében.
  • OneLake hivatkozási korlátozások: Az S3/GCS típusú hivatkozások esetében az ABFS-útvonalak helyett használjon csatlakoztatott útvonalakat a cp() és fastcp() műveletekhez.
  • Régiók közötti korlátozások: fastcp() nem támogatja a oneLake-fájlok régiók közötti másolását. A cp() használható helyette.
  • Futtatókörnyezeti verzió: A NotebookUtils a Spark 3.4 (1.2-es futtatókörnyezet) és újabb verziók használatára készült.
  • cp() viselkedés a Python-jegyzetfüzetekben: A Python-jegyzetfüzetekben a cp() belsőleg ugyanazt az azcopy-alapú mechanizmust használja, mint a fastcp(), így a két módszer azonosan viselkedik.

A NotebookUtils ugyanúgy működik a fájlrendszerrel, mint a Spark API-k. Vegyük példának a notebookutils.fs.mkdirs() és a Lakehouse használatát:

Usage Relatív elérési út a HDFS-gyökérből Az ABFS fájlrendszer abszolút elérési útja A helyi fájlrendszer abszolút elérési útja az illesztőprogram-csomópontban
Nem alapértelmezett Lakehouse Nem támogatott notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Alapértelmezett Lakehouse Könyvtár a "Fájlok" vagy a "Táblák" területen: 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>")

  • Az alapértelmezett Lakehouse esetében a fájlelérési útvonalak a jegyzetfüzethez vannak csatolva, és a fájltár alapértelmezett időtúllépése 120 másodperc. Ez azt jelenti, hogy a fájlok 120 másodpercig gyorsítótárazva lesznek a jegyzetfüzet helyi ideiglenes mappájában, még akkor is, ha eltávolítják őket a Lakehouse-ból. Ha módosítani szeretné az időtúllépési szabályt, leválaszthatja az alapértelmezett Lakehouse-fájlútvonalakat, és újra csatlakoztathatja őket egy másik fileCacheTimeout értékkel.

  • Nem alapértelmezett Lakehouse-konfigurációk esetén a Lakehouse-útvonalak csatlakoztatása során beállíthatja a megfelelő fileCacheTimeout paramétert. Az időtúllépés 0 értékre állítása biztosítja, hogy a legújabb fájl lekérhető legyen a Lakehouse-kiszolgálóról.

Fájlok listázása

A címtár tartalmának listázásához használja a notebookutils.fs.ls('Your directory path') következőt: Például:

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

Az notebookutils.fs.ls() API a jegyzetfüzet típusától függően eltérően viselkedik egy relatív elérési út használatakor.

  • Spark-jegyzetfüzetben: A relatív elérési út az alapértelmezett Lakehouse ABFSS-elérési úthoz képest van. Például notebookutils.fs.ls("Files") az alapértelmezett Lakehouse Files könyvtárára mutat.

    Például:

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

  • Python-jegyzetfüzetben: A relatív elérési út a helyi fájlrendszer munkakönyvtárához viszonyítva van, amely alapértelmezés szerint a /home/trusted-service-user/work. Ezért a relatív elérési út notebookutils.fs.ls("/lakehouse/default/Files") helyett a teljes elérési utat kell használnia a Files könyvtár eléréséhez az alapértelmezett Lakehouse-ban.

    Például:

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

Fájltulajdonságok megtekintése

A notebookutils.fs.ls() segítségével megvizsgálhatja a fájl tulajdonságait, például a fájlnevet, a fájl elérési útját, a fájlméretet, és hogy egy elem fájl vagy könyvtár-e.

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

Ha olvashatóbb kimenetet szeretne, használjon f-sztringeket:

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

Új címtár létrehozása

Hozzon létre egy könyvtárat, ha nem létezik, beleértve a szükséges szülőkönyvtárakat is.

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

Fájl másolása

Fájl vagy könyvtár másolása fájlrendszerek között. Állítsa be recurse=True a könyvtárak rekurzív másolására.

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

Megjegyzés:

Python-jegyzetfüzet megjegyzés: A Python-jegyzetfüzetekben a cp() belsőleg ugyanazt az azcopy-alapú mechanizmust használja, mint a fastcp(), ami mindkét módszer számára hatékony teljesítményt biztosít. A OneLake-parancsikon korlátozásai miatt, ha az adatok S3/GCS típusú parancsikonból való másolására van szükség notebookutils.fs.cp() , javasoljuk, hogy csatlakoztatott elérési utat használjon abfss-elérési út helyett.

Jótanács

Mindig ellenőrizze a logikai visszatérési értéket annak ellenőrzéséhez, hogy a művelet sikeres volt-e. Használja a notebookutils.fs.exists()-t, hogy ellenőrizze a forrás elérési útját, mielőtt megkezdi a másolási műveletet.

Az alábbi példa egy tárterületközi példányt mutat be az alapértelmezett Lakehouse-ból egy ADLS Gen2-fiókba:

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

Hatékony fájlmásolás

Hatékonyabb másolási műveletekhez használható fastcp , különösen nagy adatkötetek esetén. A recurse paraméter alapértelmezés szerint a következő.True

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

Jótanács

Használja a fastcp()-t a cp() helyett nagy adatátvitel esetén. A fastcp módszer az azcopy-t használja a motorháztető alatt, ami jelentősen jobb átviteli sebességet biztosít a tömeges fájlműveletekhez. A Python-jegyzetfüzetekben mindkettő cp() , és fastcp() ugyanazt a mögöttes mechanizmust használja.

Tartsa szem előtt az alábbi szempontokat:

  • notebookutils.fs.fastcp() nem támogatja a oneLake-fájlok régiók közötti másolását. Ebben az esetben notebookutils.fs.cp() használhatja helyette.
  • A OneLake-parancsikon korlátozásai miatt, ha az adatok S3/GCS típusú parancsikonból való másolására van szükség notebookutils.fs.fastcp() , javasoljuk, hogy csatlakoztatott elérési utat használjon abfss-elérési út helyett.

Fájltartalom előnézete

Adja vissza egy fájl első max_bytes bájtját UTF-8 karakterláncként.

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

Jótanács

Nagyméretű fájlok esetén használja head() a megfelelő max_bytes értékkel a memóriaproblémák elkerülése érdekében. Az alapértelmezett érték 100 KB (1024 * 100).

Az alábbi példa egy fájl első 1000 bájtját olvassa be:

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

Megjegyzés:

Az alapértelmezett érték max_bytes nyelvenként eltérő: a Python- és Scala-jegyzetfüzetek 102400 (100 KB) használatával működnek, míg az R-jegyzetfüzetek 65535 (64 KB) használatával működnek. A Scalában ez a paraméter neve maxBytes.

Fájl áthelyezése

Fájl vagy könyvtár áthelyezése fájlrendszerek között.

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

Fontos

Az create_path alapértelmezett paramétere a futásidőtől függően változik.

  • Spark-jegyzetfüzetek (PySpark, Scala, R): alapértelmezés szerint False (false a Scalában, FALSE az R-ben). A szülőkönyvtárnak léteznie kell az áthelyezési művelet előtt.
  • Python-jegyzetfüzetek: alapértelmezés szerint True. A szülőkönyvtár automatikusan létrejön, ha nem létezik.

A futtatókörnyezetek konzisztens viselkedésének biztosítása érdekében explicit módon állítsa be a paramétert a create_path kódban. A Scalában ez a paraméter neve createPath.

Ha tisztább kódot szeretne, használjon elnevezett paramétereket:

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

Fájl írása

Írjon egy UTF-8 sztringet egy fájlba.

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

Tartalom hozzáfűzése fájlhoz

UTF-8 karaktersor hozzáfűzése egy fájlhoz.

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

Fontos

notebookutils.fs.append() és notebookutils.fs.put() az atomiságra vonatkozó garanciák hiánya miatt nem támogatja ugyanahhoz a fájlhoz való egyidejű írást.

Ha az notebookutils.fs.append API-t for ciklusban használja ugyanarra a fájlra való íráshoz, adjon hozzá egy sleep körülbelül 0,5–1 másodperces utasítást az ismétlődő írások között. Ennek a javaslatnak az az oka, hogy a notebookutils.fs.append API belső flush művelete aszinkron, így rövid késleltetéssel biztosítható az adatok integritása.

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

Fájl vagy könyvtár törlése

Fájl vagy könyvtár eltávolítása. Állítsa be recurse=True, hogy rekurzívan eltávolíthassa a könyvtárakat.

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

Ellenőrizze, hogy létezik-e fájl vagy könyvtár

Ellenőrizze, hogy létezik-e fájl vagy könyvtár a megadott elérési úton. Ha az elérési út létezik, akkor True-t ad vissza; ellenkező esetben False-t ad vissza.

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

Jótanács

Fájlműveletek végrehajtása előtt használja exists() a hibák megelőzésére. Ellenőrizze például, hogy létezik-e forrásfájl, mielőtt megpróbálná másolni vagy áthelyezni.

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

Fájltulajdonságok lekérése

Az elérési út tulajdonságainak lekérése név-érték párok térképeként. Ez csak az Azure Blob Storage-útvonalak esetében támogatott.

Megjegyzés:

A getProperties metódus csak Python-jegyzetfüzetekben érhető el. A Spark-jegyzetfüzetekben (PySpark, Scala vagy R) nem támogatott.

Paraméterek:

Paraméter Típus Szükséges Leírás
path Lánc Igen ABFS elérési útja a fájlhoz vagy könyvtárhoz.

Visszatér: Olyan metaadat-tulajdonságokat tartalmazó szótár (térkép), mint a fájlméret, a létrehozás időpontja, az utolsó módosítás időpontja és a tartalom típusa.

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

Kapcsolódó tartalom

  • Last updated on