Βοηθητικά προγράμματα συστήματος αρχείων NotebookUtils για το Fabric

notebookutils.fs παρέχει βοηθητικά προγράμματα για εργασία με διάφορα συστήματα αρχείων, συμπεριλαμβανομένων των Azure Data Lake Storage (ADLS) Gen2 και Azure Blob Storage. Βεβαιωθείτε ότι έχετε ρυθμίσει κατάλληλα τις παραμέτρους πρόσβασης στα Azure Data Lake Storage Gen2 και Azure Blob Storage .

Εκτελέστε τις ακόλουθες εντολές για μια επισκόπηση των διαθέσιμων μεθόδων:

notebookutils.fs.help()

Ο παρακάτω πίνακας παραθέτει τις διαθέσιμες μεθόδους συστήματος αρχείων:

Μέθοδος	Υπογραφή	Περιγραφή
`ls`	`ls(path: String): Array`	Παραθέτει τα περιεχόμενα ενός καταλόγου.
`mkdirs`	`mkdirs(path: String): Boolean`	Δημιουργεί τον δεδομένο κατάλογο εάν δεν υπάρχει, δημιουργώντας επίσης τυχόν απαραίτητους γονικούς καταλόγους.
`cp`	`cp(src: String, dest: String, recurse: Boolean = false): Boolean`	Αντιγράφει ένα αρχείο ή έναν κατάλογο, πιθανώς σε όλα τα συστήματα αρχείων.
`fastcp`	`fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean`	Αντιγράφει ένα αρχείο ή έναν κατάλογο μέσω azcopy για καλύτερη απόδοση με μεγάλους όγκους δεδομένων.
`mv`	`mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean`	Μετακινεί ένα αρχείο ή έναν κατάλογο, πιθανώς σε συστήματα αρχείων.
`put`	`put(file: String, content: String, overwrite: Boolean = false): Boolean`	Γράφει τη δεδομένη συμβολοσειρά σε ένα αρχείο, κωδικοποιημένο σε UTF-8.
`head`	`head(file: String, max_bytes: int = 1024 * 100): String`	Επιστρέφει έως και τα πρώτα `max_bytes` byte του δεδομένου αρχείου ως συμβολοσειρά κωδικοποιημένη σε UTF-8.
`append`	`append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean`	Προσαρτά το περιεχόμενο σε ένα αρχείο.
`rm`	`rm(path: String, recurse: Boolean = false): Boolean`	Καταργεί ένα αρχείο ή έναν κατάλογο.
`exists`	`exists(path: String): Boolean`	Ελέγχει εάν υπάρχει αρχείο ή κατάλογος.
`getProperties`	`getProperties(path: String): Map`	Λαμβάνει τις ιδιότητες της δεδομένης διαδρομής. Διατίθεται μόνο σε σημειωματάρια Python (δεν υποστηρίζεται σε PySpark, Scala ή R).

Σημείωμα

Όλες οι μέθοδοι συστήματος αρχείων είναι διαθέσιμες σε σημειωματάρια Python, PySpark, Scala και R, εκτός εάν αναφέρεται διαφορετικά. Η Scala χρησιμοποιεί ονόματα παραμέτρων camelCase (για παράδειγμα, createPath αντί για create_path, maxBytes αντί για max_bytes).

Για τις λειτουργίες προσάρτησης και αποπροσάρτησης, ανατρέξτε στην ενότητα Προσάρτηση και αποπροσάρτηση αρχείου.

Σημείωμα

Λάβετε υπόψη τους ακόλουθους περιορισμούς και ζητήματα όταν εργάζεστε με notebookutils.fs:

Η συμπεριφορά διαδρομής διαφέρει ανάλογα με τον τύπο σημειωματαρίου: Στα σημειωματάρια Spark, οι σχετικές διαδρομές επιλύονται στην προεπιλεγμένη διαδρομή Lakehouse ABFSS. Στα σημειωματάρια Python, οι σχετικές διαδρομές επιλύονται στον κατάλογο εργασίας του τοπικού συστήματος αρχείων (/home/trusted-service-user/work).
Περιορισμοί ταυτόχρονης εγγραφής: notebookutils.fs.append() και notebookutils.fs.put() δεν υποστηρίζουν ταυτόχρονες εγγραφές στο ίδιο αρχείο λόγω έλλειψης εγγυήσεων ατομικότητας.
Καθυστέρηση βρόχου προσάρτησης: Όταν χρησιμοποιείτε notebookutils.fs.append() σε βρόχους, προσθέστε 0,5-1 δευτερόλεπτο ύπνου μεταξύ των εγγραφών για ακεραιότητα δεδομένων.
Περιορισμοί συντομεύσεων OneLake: Για συντομεύσεις τύπου S3/GCS, χρησιμοποιήστε μονταρισμένες διαδρομές αντί για διαδρομές ABFS για cp()fastcp() και λειτουργίες.
Περιορισμοί μεταξύ περιοχών: fastcp() δεν υποστηρίζει την αντιγραφή αρχείων στο OneLake σε όλες τις περιοχές. Χρησιμοποιήστε το cp() αντί για αυτό.
Έκδοση χρόνου εκτέλεσης: Το NotebookUtils έχει σχεδιαστεί για να λειτουργεί με το Spark 3.4 (Runtime v1.2) και νεότερη έκδοση.
cp() συμπεριφορά σε σημειωματάρια Python: Στα σημειωματάρια Python, cp() χρησιμοποιεί εσωτερικά τον ίδιο μηχανισμό που βασίζεται σε azcopy με fastcp()το , επομένως και οι δύο μέθοδοι συμπεριφέρονται πανομοιότυπα.

Το NotebookUtils λειτουργεί με το σύστημα αρχείων με τον ίδιο τρόπο όπως τα Spark API. Πάρτε notebookutils.fs.mkdirs() για παράδειγμα και τη χρήση lakehouse:

χρήσης	Σχετική διαδρομή από ρίζα HDFS	Απόλυτη διαδρομή για το σύστημα αρχείων ABFS	Απόλυτη διαδρομή για το τοπικό σύστημα αρχείων στον κόμβο προγράμματος οδήγησης
Μη προεπιλεγμένο λιμναίο σπίτι	Δεν υποστηρίζεται	`notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")`	`notebookutils.fs.mkdirs("file:/<new_dir>")`
Προεπιλεγμένη λίμνη	Κατάλογος κάτω από τα «Αρχεία» ή τους «Πίνακες»: `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>")`

Για το προεπιλεγμένο lakehouse, οι διαδρομές αρχείων μονταρίζονται στο σημειωματάριό σας με προεπιλεγμένο χρονικό όριο cache αρχείων 120 δευτερολέπτων. Αυτό σημαίνει ότι τα αρχεία αποθηκεύονται προσωρινά στον τοπικό προσωρινό φάκελο του σημειωματαρίου για 120 δευτερόλεπτα, ακόμα και αν καταργηθούν από το lakehouse. Εάν θέλετε να αλλάξετε τον κανόνα χρονικού ορίου, μπορείτε να καταργήσετε την προσάρτηση των προεπιλεγμένων διαδρομών αρχείων lakehouse και να τις μοντάρετε ξανά με διαφορετική fileCacheTimeout τιμή.
Για μη προεπιλεγμένες διαμορφώσεις lakehouse, μπορείτε να ορίσετε την κατάλληλη fileCacheTimeout παράμετρο κατά την προσάρτηση των διαδρομών lakehouse. Η ρύθμιση του χρονικού ορίου σε 0 διασφαλίζει ότι το πιο πρόσφατο αρχείο λαμβάνεται από τον διακομιστή lakehouse.

Λίστα αρχείων

Για να παραθέσετε το περιεχόμενο ενός καταλόγου, χρησιμοποιήστε notebookutils.fs.ls('Your directory path'). Για παράδειγμα:

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 συμπεριφέρεται διαφορετικά όταν χρησιμοποιείται μια σχετική διαδρομή, ανάλογα με τον τύπο του σημειωματαρίου.

Σε ένα σημειωματάριο Spark: Η σχετική διαδρομή είναι σχετική με την προεπιλεγμένη διαδρομή ABFSS του Lakehouse. Για παράδειγμα, notebookutils.fs.ls("Files") δείχνει στον κατάλογο Files στον προεπιλεγμένο κατάλογο Lakehouse.

Για παράδειγμα:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
Σε ένα σημειωματάριο Python: Η σχετική διαδρομή είναι σχετική με τον κατάλογο εργασίας του τοπικού συστήματος αρχείων, ο οποίος από προεπιλογή είναι /home/trusted-service-user/work. Επομένως, θα πρέπει να χρησιμοποιήσετε την πλήρη διαδρομή αντί για μια σχετική διαδρομή notebookutils.fs.ls("/lakehouse/default/Files") για πρόσβαση στον Files κατάλογο στο προεπιλεγμένο Lakehouse.

Για παράδειγμα:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Προβολή ιδιοτήτων αρχείου

Χρησιμοποιείται για 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)

Χρησιμοποιήστε f-strings εάν θέλετε πιο ευανάγνωστη έξοδο:

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

Δημιουργία νέου καταλόγου

Δημιουργήστε έναν κατάλογο εάν δεν υπάρχει, συμπεριλαμβανομένων τυχόν απαραίτητων γονικών καταλόγων.

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

Αντιγραφή αρχείου

Αντιγράψτε ένα αρχείο ή έναν κατάλογο σε όλα τα συστήματα αρχείων. Ρυθμίστε recurse=True την αναδρομική αντιγραφή καταλόγων.

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

Σημείωμα

Σημείωση σημειωματάριου Python: Στα σημειωματάρια Python, cp() χρησιμοποιεί εσωτερικά τον ίδιο μηχανισμό που βασίζεται σε azcopy με fastcp()το , παρέχοντας αποτελεσματική απόδοση και για τις δύο μεθόδους. Λόγω των περιορισμών της συντόμευσης OneLake, όταν χρειάζεται να χρησιμοποιήσετε notebookutils.fs.cp() τη συντόμευση για την αντιγραφή δεδομένων από τη συντόμευση τύπου S3/GCS, συνιστάται να χρησιμοποιήσετε μια μονταρισμένη διαδρομή αντί για μια διαδρομή abfss.

Συμβουλή

Ελέγχετε πάντα την τιμή Boolean return για να επαληθεύσετε εάν η λειτουργία ήταν επιτυχής. Χρησιμοποιήστε notebookutils.fs.exists() το για να επαληθεύσετε τη διαδρομή προέλευσης πριν ξεκινήσετε μια λειτουργία αντιγραφής.

Το παρακάτω παράδειγμα εμφανίζει ένα αντίγραφο πολλαπλού χώρου αποθήκευσης από το προεπιλεγμένο lakehouse σε έναν λογαριασμό ADLS Gen2:

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

Εκτέλεση αρχείου αντιγραφής

Χρησιμοποιήστε το fastcp για πιο αποτελεσματικές λειτουργίες αντιγραφής, ειδικά με μεγάλους όγκους δεδομένων. Η recurse προεπιλεγμένη παράμετρος είναι True.

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

Συμβουλή

Χρησιμοποιήστε το fastcp() αντί cp() για μεγάλες μεταφορές δεδομένων. Η fastcp μέθοδος χρησιμοποιεί azcopy κάτω από την κουκούλα, η οποία παρέχει σημαντικά καλύτερη απόδοση για λειτουργίες μαζικών αρχείων. Στα σημειωματάρια Python, και τα δύο cp() και fastcp() χρησιμοποιούν τον ίδιο υποκείμενο μηχανισμό.

Λάβετε υπόψη αυτές τις σκέψεις:

notebookutils.fs.fastcp() δεν υποστηρίζει την αντιγραφή αρχείων στο OneLake σε όλες τις περιοχές. Σε αυτήν την περίπτωση, μπορείτε να χρησιμοποιήσετε τη συνάρτηση notebookutils.fs.cp() αντί για αυτό.
Λόγω των περιορισμών της συντόμευσης OneLake, όταν χρειάζεται να χρησιμοποιήσετε notebookutils.fs.fastcp() τη συντόμευση για την αντιγραφή δεδομένων από τη συντόμευση τύπου S3/GCS, συνιστάται να χρησιμοποιήσετε μια μονταρισμένη διαδρομή αντί για μια διαδρομή abfss.

Προεπισκόπηση περιεχομένου αρχείου

Επιστρέψτε έως και τα πρώτα max_bytes byte ενός αρχείου ως συμβολοσειρά UTF-8.

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

Συμβουλή

Για μεγάλα αρχεία, χρησιμοποιήστε το head() με την κατάλληλη max_bytes τιμή για να αποφύγετε προβλήματα μνήμης. Η προεπιλεγμένη τιμή είναι 100 KB (1024 * 100).

Το παρακάτω παράδειγμα διαβάζει τα πρώτα 1.000 byte ενός αρχείου:

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

Σημείωμα

Η προεπιλεγμένη τιμή για max_bytes διαφέρει μεταξύ των γλωσσών: τα σημειωματάρια Python και Scala χρησιμοποιούν 102400 (100 KB), ενώ τα σημειωματάρια R χρησιμοποιούν 65535 (64 KB). Στη Scala, αυτή η παράμετρος ονομάζεται maxBytes.

Μετακίνηση αρχείου

Μετακινήστε ένα αρχείο ή έναν κατάλογο σε συστήματα αρχείων.

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

Σημαντικό

Η create_path προεπιλογή της παραμέτρου διαφέρει ανάλογα με το χρόνο εκτέλεσης:

Σημειωματάρια Spark (PySpark, Scala, R): προεπιλογή σε False (false στη Scala, FALSE στην R). Ο γονικός κατάλογος πρέπει να υπάρχει πριν από τη λειτουργία μετακίνησης.
Python notebooks: προεπιλογή .True Ο γονικός κατάλογος δημιουργείται αυτόματα εάν δεν υπάρχει.

Για να εξασφαλίσετε συνεπή συμπεριφορά σε όλους τους χρόνους εκτέλεσης, ορίστε ρητά την create_path παράμετρο στον κώδικά σας. Στη Scala, αυτή η παράμετρος ονομάζεται createPath.

Χρησιμοποιήστε ονομαστικές παραμέτρους εάν θέλετε σαφέστερο κώδικα:

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

Σύνταξη αρχείου

Γράψτε μια συμβολοσειρά UTF-8 σε ένα αρχείο.

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

Προσάρτηση περιεχομένου σε ένα αρχείο

Προσθέστε μια συμβολοσειρά UTF-8 σε ένα αρχείο.

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

Σημαντικό

notebookutils.fs.append() και notebookutils.fs.put() δεν υποστηρίζουν ταυτόχρονη εγγραφή στο ίδιο αρχείο λόγω έλλειψης εγγυήσεων ατομικότητας.

Όταν χρησιμοποιείτε το notebookutils.fs.append API σε βρόχο for για εγγραφή στο ίδιο αρχείο, προσθέστε μια sleep δήλωση περίπου 0.5 έως 1 δευτερολέπτου μεταξύ των επαναλαμβανόμενων εγγραφών. Αυτή η πρόταση οφείλεται στο γεγονός ότι η εσωτερική λειτουργία notebookutils.fs.append του flush API είναι ασύγχρονη, επομένως, μια μικρή καθυστέρηση συμβάλλει στη διασφάλιση της ακεραιότητας των δεδομένων.

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

Διαγραφή αρχείου ή καταλόγου

Καταργήστε ένα αρχείο ή έναν κατάλογο. Ρυθμίστε recurse=True την αναδρομική κατάργηση καταλόγων.

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

Ελέγξτε εάν υπάρχει αρχείο ή κατάλογος

Ελέγξτε εάν υπάρχει αρχείο ή κατάλογος στην καθορισμένη διαδρομή. Επιστρέφει True αν υπάρχει η διαδρομή. Διαφορετικά, επιστρέφει False.

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

Συμβουλή

Χρησιμοποιήστε το exists() πριν από την εκτέλεση λειτουργιών αρχείων για την αποφυγή σφαλμάτων. Για παράδειγμα, βεβαιωθείτε ότι υπάρχει ένα αρχείο προέλευσης πριν προσπαθήσετε να το αντιγράψετε ή να το μετακινήσετε.

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

Λήψη ιδιοτήτων αρχείου

Λάβετε ιδιότητες για μια διαδρομή ως χάρτη ζευγών ονόματος-τιμής. Υποστηρίζεται μόνο για διαδρομές χώρου αποθήκευσης αντικειμένων blob Azure.

Σημείωμα

Η getProperties μέθοδος είναι διαθέσιμη μόνο σε σημειωματάρια Python. Δεν υποστηρίζεται σε σημειωματάρια Spark (PySpark, Scala ή R).

Παράμετροι:

Παράμετρος	Τύπος	Υποχρεωτικό	Περιγραφή
`path`	Συμβλοσειρά	Ναι	Διαδρομή ABFS προς το αρχείο ή τον κατάλογο.

Επιστροφές: Ένα λεξικό (χάρτης) που περιέχει ιδιότητες μεταδεδομένων όπως μέγεθος αρχείου, χρόνος δημιουργίας, χρόνος τελευταίας τροποποίησης και τύπος περιεχομένου.

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

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-04-02

Βοηθητικά προγράμματα συστήματος αρχείων NotebookUtils για το Fabric

Λίστα αρχείων

Προβολή ιδιοτήτων αρχείου

Δημιουργία νέου καταλόγου

Αντιγραφή αρχείου

Εκτέλεση αρχείου αντιγραφής

Προεπισκόπηση περιεχομένου αρχείου

Μετακίνηση αρχείου

Σύνταξη αρχείου

Προσάρτηση περιεχομένου σε ένα αρχείο

Διαγραφή αρχείου ή καταλόγου

Ελέγξτε εάν υπάρχει αρχείο ή κατάλογος

Λήψη ιδιοτήτων αρχείου

Σχετικό περιεχόμενο

Σχόλια

Πρόσθετοι πόροι