NotebookUtils (πρώην MSSparkUtils) για Fabric

Τα Βοηθητικά προγράμματα σημειωματάριου (NotebookUtils) είναι ένα ενσωματωμένο πακέτο που σας βοηθά να εκτελείτε εύκολα συνήθεις εργασίες στο Fabric Notebook. Μπορείτε να χρησιμοποιήσετε το NotebookUtils για να εργαστείτε με συστήματα αρχείων, για να λάβετε μεταβλητές περιβάλλοντος, να αλληλουχήσετε σημειωματάρια και να εργαστείτε με μυστικά. Το πακέτο NotebookUtils είναι διαθέσιμο στη Scala PySpark (Python), στα σημειωματάρια SparkR και στις διοχετεύσεις Fabric.

Note

Το MsSparkUtils μετονομάζεται επίσημα σε NotebookUtils. Ο υπάρχων κώδικας παραμένει συμβατός με προηγούμενες εκδόσεις και δεν προκαλεί αλλαγές διακοπής. Συνιστάται ιδιαίτερα η αναβάθμιση σε notebookutils για να εξασφαλίσετε συνεχή υποστήριξη και πρόσβαση σε νέες δυνατότητες. Ο χώρος ονομάτων mssparkutils θα αποσυρθεί στο μέλλον.
Το NotebookUtils έχει σχεδιαστεί για χρήση με το Spark 3.4(Runtime v1.2) και νεότερες εκδόσεις. Όλες οι νέες δυνατότητες και ενημερώσεις υποστηρίζονται αποκλειστικά με τον χώρο ονομάτων σημειωματάριων στο μέλλον.

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

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

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

notebookutils.fs.help()

Output

notebookutils.fs provides utilities for working with various FileSystems.

Below is overview about the available methods:

cp(from: String, to: String, recurse: Boolean = false): Boolean -> Copies a file or directory, possibly across FileSystems
fastcp(from: String, to: String, recurse: Boolean = true): Boolean -> Copies a file or directory via azcopy, possibly across FileSystems
mv(from: String, to: String, createPath: Boolean = false, overwrite: Boolean = false): Boolean -> Moves a file or directory, possibly across FileSystems
ls(dir: String): Array -> Lists the contents of a directory
mkdirs(dir: String): Boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
put(file: String, contents: String, overwrite: Boolean = false): Boolean -> Writes the given String out to a file, encoded in UTF-8
head(file: String, maxBytes: int = 1024 * 100): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
append(file: String, content: String, createFileIfNotExists: Boolean): Boolean -> Append the content to a file
rm(dir: String, recurse: Boolean = false): Boolean -> Removes a file or directory
exists(file: String): Boolean -> Check if a file or directory exists
mount(source: String, mountPoint: String, extraConfigs: Map[String, Any]): Boolean -> Mounts the given remote storage directory at the given mount point
unmount(mountPoint: String): Boolean -> Deletes a mount point
mounts(): Array[MountPointInfo] -> Show information about what is mounted
getMountPath(mountPoint: String, scope: String = ""): String -> Gets the local path of the mount point

Use notebookutils.fs.help("methodName") for more info about a method.

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

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

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

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

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

notebookutils.fs.ls("Files/tmp") # The relatvie path may work with different base path, details in below 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # The absolute path, like: ABFS file system
notebookutils.fs.ls("file:/tmp")  # The 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")
```

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

Αυτή η μέθοδος επιστρέφει ιδιότητες αρχείου όπως το όνομα αρχείου, τη διαδρομή αρχείου, το μέγεθος αρχείου και εάν πρόκειται για κατάλογο και αρχείο.

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

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

Αυτή η μέθοδος δημιουργεί τον δεδομένο κατάλογο εάν δεν υπάρχει και δημιουργεί τυχόν απαραίτητους γονικοί κατάλογοι.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # based on ABFS file system 
notebookutils.fs.ls("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)

Note

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

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

Αυτή η μέθοδος προσφέρει μια πιο αποτελεσματική προσέγγιση για την αντιγραφή ή τη μετακίνηση αρχείων, ιδιαίτερα όταν αντιμετωπίζετε μεγάλους όγκους δεδομένων. Για βελτιωμένες επιδόσεις στο Fabric, συνιστάται να χρησιμοποιήσετε fastcp ως υποκατάστατο της παραδοσιακής cp μεθόδου.

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

Εκτιμήσεις:

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

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

Αυτή η μέθοδος επιστρέφει έως τα πρώτα byte "maxBytes" του δεδομένου αρχείου ως Συμβολοσειρά κωδικοποιημένη σε UTF-8.

notebookutils.fs.head('file path', maxBytes to read)

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

Αυτή η μέθοδος μετακινεί ένα αρχείο ή κατάλογο και υποστηρίζει κινήσεις μεταξύ συστημάτων αρχείων.

notebookutils.fs.mv('source file or directory', 'destination directory', True) # Set the last parameter as True to firstly create the parent directory if it does not exist
notebookutils.fs.mv('source file or directory', 'destination directory', True, True) # Set the third parameter to True to firstly create the parent directory if it does not exist. Set the last parameter to True to overwrite the updates.

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

Αυτή η μέθοδος εγγράφει τη δεδομένη συμβολοσειρά σε ένα αρχείο, κωδικοποιημένη σε UTF-8.

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

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

Αυτή η μέθοδος προσαρτά τη δεδομένη συμβολοσειρά σε ένα αρχείο, κωδικοποιημένο σε UTF-8.

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

Εκτιμήσεις:

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

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

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

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

Προσάρτηση/αποπροσάρτηση καταλόγου

Βρείτε περισσότερες πληροφορίες σχετικά με τη λεπτομερή χρήση στο θέμα Μοντάρετε αρχείο και κατάργησηmount.

Βοηθητικά προγράμματα φορητών υπολογιστών

Χρησιμοποιήστε τα Βοηθητικά προγράμματα σημειωματάριου για να εκτελέσετε ένα σημειωματάριο ή κλείστε ένα σημειωματάριο με μια τιμή. Εκτελέστε την ακόλουθη εντολή για να δείτε μια επισκόπηση των διαθέσιμων μεθόδων:

notebookutils.notebook.help()

Output:


The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map, workspace: String): String -> This method runs a notebook and returns its exit value.
runMultiple(DAG: Any): Map[String, MsNotebookRunResult] -> Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> This method check if the DAG is correctly defined.

Below methods are only support Fabric Notebook.
create(name: String, description: String = "", content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = ""): Artifact -> Create a new Notebook.
get(name: String, workspaceId: String = ""): Artifact -> Get a Notebook by name or id.
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact -> Update a Artifact by name.
delete(name: String, workspaceId: String = ""): Boolean -> Delete a Notebook by name.
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact] -> List all Notebooks in the workspace.
updateDefinition(name: String, content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = "") -> Update the definition of a Notebook.

Use notebookutils.notebook.help("methodName") for more info about a method.

Note

Τα βοηθητικά προγράμματα σημειωματάριου δεν ισχύουν για τους ορισμούς εργασίας Apache Spark (SJD).

Αναφορά σημειωματάριου

Αυτή η μέθοδος αναφέρεται σε ένα σημειωματάριο και επιστρέφει την τιμή εξόδου του. Μπορείτε να εκτελέσετε κλήσεις συνάρτησης ένθεσης σε ένα σημειωματάριο με αλληλεπιδραστικό τρόπο ή σε μια διοχέτευση. Το σημειωματάριο στο οποίο γίνεται αναφορά εκτελείται στον χώρο συγκέντρωσης Spark του σημειωματάριου που καλεί αυτήν τη συνάρτηση.

notebookutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>, <workspaceId>)

Για παράδειγμα:

notebookutils.notebook.run("Sample1", 90, {"input": 20 })

Το υφασμάτινο σημειωματάριο υποστηρίζει επίσης την αναφορά σε σημειωματάρια σε πολλούς χώρους εργασίας, καθορίζοντας το αναγνωριστικό χώρου εργασίας.

notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

Μπορείτε να ανοίξετε τη σύνδεση στιγμιότυπου της εκτέλεσης αναφοράς στην έξοδο κελιού. Το στιγμιότυπο καταγράφει τα αποτελέσματα εκτέλεσης κώδικα και σας επιτρέπει να εντοπίσετε εύκολα μια εκτέλεση αναφοράς.

Εκτιμήσεις:

Το σημειωματάριο αναφοράς μεταξύ χώρων εργασίας υποστηρίζεται από την έκδοση 1.2 του περιβάλλοντος εκτέλεσης και νεότερες εκδόσεις.
Εάν χρησιμοποιείτε τα αρχεία στην περιοχή Πόρος σημειωματαρίου, χρησιμοποιήστε notebookutils.nbResPath το στο αναφερόμενο σημειωματάριο για να βεβαιωθείτε ότι οδηγεί στον ίδιο φάκελο με την αλληλεπιδραστική εκτέλεση.
Η εκτέλεση αναφοράς επιτρέπει στα θυγατρικά σημειωματάρια να εκτελούνται μόνο εάν χρησιμοποιούν το ίδιο λιμναίο σπίτι με το γονικό, κληρονομούν το λιμναίο σπίτι του γονέα ή δεν ορίζουν κανένα. Η εκτέλεση αποκλείεται εάν το θυγατρικό καθορίσει διαφορετικό lakehouse από το γονικό σημειωματάριο. Για να παρακάμψετε αυτόν τον έλεγχο, ορίστε useRootDefaultLakehouse: True.

Αναφορά εκτέλεσης πολλών σημειωματάριων παράλληλα

Η μέθοδος notebookutils.notebook.runMultiple() σάς επιτρέπει να εκτελείτε πολλά σημειωματάρια παράλληλα ή με μια προκαθορισμένη τοπολογική δομή. Το API χρησιμοποιεί έναν μηχανισμό υλοποίησης πολλών νημάτων εντός μιας περιόδου λειτουργίας spark, το οποίο σημαίνει ότι οι εκτελέσεις σημειωματάριου αναφοράς μοιράζονται τους υπολογιστικούς πόρους.

Με notebookutils.notebook.runMultiple()το , μπορείτε να κάνετε τα εξής:

Εκτελέστε πολλά σημειωματάρια ταυτόχρονα, χωρίς να πρέπει να ολοκληρωθεί το καθένα.
Καθορίστε τις εξαρτήσεις και τη σειρά εκτέλεσης για τα σημειωματάριά σας, χρησιμοποιώντας μια απλή μορφή JSON.
Βελτιστοποιήστε τη χρήση των υπολογιστικών πόρων Spark και μειώστε το κόστος των έργων σας Fabric.
Προβάλετε τα Στιγμιότυπα κάθε εγγραφής εκτέλεσης σημειωματάριου στην έξοδο και εντοπίστε εύκολα τις εργασίες του σημειωματάριου/παρακολουθήστε τις εργασίες σας.
Λάβετε την αξία εξόδου κάθε εκτελεστικής δραστηριότητας και χρησιμοποιήστε τις σε εργασίες κατάντη.

Μπορείτε επίσης να δοκιμάσετε να εκτελέσετε το notebookutils.notebook.help("runMultiple") για να βρείτε το παράδειγμα και τη λεπτομερή χρήση.

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

notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])

Το αποτέλεσμα εκτέλεσης από το ριζικό σημειωματάριο είναι το εξής:

Ακολουθεί ένα παράδειγμα εκτέλεσης σημειωματάριων με τοπολογική δομή που χρησιμοποιεί notebookutils.notebook.runMultiple(). Χρησιμοποιήστε αυτήν τη μέθοδο για να οργανώσετε εύκολα σημειωματάρια μέσω μιας εμπειρίας κώδικα.

# run multiple notebooks with parameters
DAG = {
    "activities": [
        {
            "name": "NotebookSimple", # activity name, must be unique
            "path": "NotebookSimple", # notebook path
            "timeoutPerCellInSeconds": 90, # max timeout for each cell, default to 90 seconds
            "args": {"p1": "changed value", "p2": 100}, # notebook parameters
        },
        {
            "name": "NotebookSimple2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200}
        },
        {
            "name": "NotebookSimple2.2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["NotebookSimple"] # list of activity names that this activity depends on
        }
    ],
    "timeoutInSeconds": 43200, # max timeout for the entire DAG, default to 12 hours
    "concurrency": 50 # max number of notebooks to run concurrently, default to 50
}
notebookutils.notebook.runMultiple(DAG, {"displayDAGViaGraphviz": False})

Το αποτέλεσμα εκτέλεσης από το ριζικό σημειωματάριο είναι το εξής:

Παρέχουμε επίσης μια μέθοδο για να ελέγξετε εάν το DAG έχει οριστεί σωστά.

notebookutils.notebook.validateDAG(DAG)

Εκτιμήσεις:

Ο βαθμός παραλληλισμού της εκτέλεσης πολλαπλού σημειωματάριου περιορίζεται στον συνολικό διαθέσιμο υπολογιστικό πόρο μιας περιόδου λειτουργίας Spark.
Ο προεπιλεγμένος αριθμός ταυτόχρονων σημειωματάριων είναι 50 για το σημειωματάριο Spark, ενώ είναι προεπιλεγμένος είναι 25 για το Python Notebook. Μπορείτε να προσαρμόσετε αυτήν την τιμή, αλλά ο υπερβολικός παραλληλισμός μπορεί να οδηγήσει σε προβλήματα σταθερότητας και απόδοσης λόγω της υψηλής χρήσης υπολογιστικών πόρων. Εάν προκύψουν προβλήματα, εξετάστε το ενδεχόμενο διαχωρισμού σημειωματαρίων σε πολλές runMultiple κλήσεις ή μείωσης του ταυτοχρονισμού προσαρμόζοντας το πεδίο ταυτοχρονισμού στην παράμετρο DAG.
Το προεπιλεγμένο χρονικό όριο για ολόκληρο το DAG είναι 12 ώρες και το προεπιλεγμένο χρονικό όριο για κάθε κελί στο θυγατρικό σημειωματάριο είναι 90 δευτερόλεπτα. Μπορείτε να αλλάξετε το χρονικό όριο ορίζοντας τα πεδία timeoutInSeconds και timeoutPerCellInSeconds στην παράμετρο DAG.

Έξοδος από ένα σημειωματάριο

Αυτή η μέθοδος εξέρχεται από ένα σημειωματάριο με μια τιμή. Μπορείτε να εκτελέσετε κλήσεις συνάρτησης ένθεσης σε ένα σημειωματάριο με αλληλεπιδραστικό τρόπο ή σε μια διοχέτευση.

Όταν καλείτε μια συνάρτηση exit() από ένα σημειωματάριο αλληλεπιδραστικά, το σημειωματάριο Fabric δημιουργεί μια εξαίρεση, παραλείπει την εκτέλεση των επόμενων κελιών και διατηρεί ζωντανή την περίοδο λειτουργίας Spark.
Όταν ενορχηστρώνει ένα σημειωματάριο σε μια διοχέτευση που καλεί μια συνάρτηση exit(), η δραστηριότητα σημειωματάριου επιστρέφει με μια τιμή εξόδου. Αυτό ολοκληρώνει την εκτέλεση της διοχέτευσης και διακόπτει την περίοδο λειτουργίας Spark.
Όταν καλείτε μια συνάρτηση exit() σε ένα σημειωματάριο που αναφέρεται, το Fabric Spark θα σταματήσει την περαιτέρω εκτέλεση του αναφερόμενου σημειωματαρίου και θα συνεχίσει να εκτελεί τα επόμενα κελιά στο κύριο σημειωματάριο που καλεί τη συνάρτηση run(). Για παράδειγμα: Το Notebook1 έχει τρία κελιά και καλεί μια συνάρτηση exit() στο δεύτερο κελί. Notebook2 έχει πέντε κελιά και καλεί run(notebook1) στο τρίτο κελί. Όταν εκτελείτε το Notebook2, το Notebook1 σταματά στο δεύτερο κελί όταν χτυπάτε τη συνάρτηση exit(). Το Notebook2 συνεχίζει να εκτελεί το τέταρτο κελί και το πέμπτο κελί του.

notebookutils.notebook.exit("value string")

Note

Η συνάρτηση exit() αντικαθιστά την τρέχουσα έξοδο κελιού. Για να αποφύγετε την απώλεια της εξόδου άλλων δηλώσεων κώδικα, καλέστε notebookutils.notebook.exit() σε ξεχωριστό κελί.

Για παράδειγμα:

Δείγμα σημειωματαρίου 1 με τα ακόλουθα δύο κελιά:

Το κελί 1 ορίζει μια παράμετρο εισόδου με προεπιλεγμένη τιμή 10.
Το κελί 2 εξέρχεται από το σημειωματάριο με είσοδο ως τιμή εξόδου.

Μπορείτε να εκτελέσετε το Δείγμα1 σε άλλο σημειωματάριο με προεπιλεγμένες τιμές:

exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)

Output:

Notebook is executed successfully with exit value 10

Μπορείτε να εκτελέσετε το Δείγμα1 σε άλλο σημειωματάριο και να ορίσετε την τιμή εισόδου ως 20:

exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)

Output:

Notebook is executed successfully with exit value 20

Διαχείριση τεχνουργημάτων σημειωματάριου

notebookutils.notebook Το παρέχει εξειδικευμένα βοηθητικά προγράμματα για τη διαχείριση στοιχείων Σημειωματάριου μέσω προγραμματισμού. Αυτά τα API μπορούν να σας βοηθήσουν να δημιουργείτε, να λαμβάνετε, να ενημερώνετε και να διαγράφετε εύκολα στοιχεία σημειωματάριου.

Για να χρησιμοποιήσετε αποτελεσματικά αυτές τις μεθόδους, εξετάστε τα παρακάτω παραδείγματα χρήσης:

Δημιουργία σημειωματάριου

with open("/path/to/notebook.ipynb", "r") as f:
    content = f.read()

artifact = notebookutils.notebook.create("artifact_name", "description", "content", "default_lakehouse_name", "default_lakehouse_workspace_id", "optional_workspace_id")

Λήψη περιεχομένου σημειωματάριου

artifact = notebookutils.notebook.get("artifact_name", "optional_workspace_id")

Ενημέρωση σημειωματάριου

updated_artifact = notebookutils.notebook.update("old_name", "new_name", "optional_description", "optional_workspace_id")

updated_artifact_definition = notebookutils.notebook.updateDefinition("artifact_name",  "content", "default_lakehouse_name", "default_Lakehouse_Workspace_name", "optional_workspace_id")

Διαγραφή σημειωματάριου

is_deleted = notebookutils.notebook.delete("artifact_name", "optional_workspace_id")

Καταχώρηση σημειωματάριων σε έναν χώρο εργασίας

artifacts_list = notebookutils.notebook.list("optional_workspace_id")

Βοηθητικά προγράμματα συνάρτησης δεδομένων χρήστη (UDF)

notebookutils.udf παρέχει βοηθητικά προγράμματα που έχουν σχεδιαστεί για την ενσωμάτωση κώδικα Σημειωματάριου με συναρτήσεις δεδομένων χρήστη (UDF). Αυτά τα βοηθητικά προγράμματα σάς επιτρέπουν να αποκτήσετε πρόσβαση σε συναρτήσεις από ένα στοιχείο UDF εντός του ίδιου χώρου εργασίας ή σε διαφορετικούς χώρους εργασίας. Στη συνέχεια, μπορείτε να καλέσετε συναρτήσεις εντός ενός στοιχείου UDF, ανάλογα με τις ανάγκες.

Ακολουθούν ορισμένα παραδείγματα για τον τρόπο χρήσης των βοηθητικών προγραμμάτων UDF:

# Get functions from a UDF item
myFunctions = notebookutils.udf.getFunctions('UDFItemName')
# Or from another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

# Display function and item details
display(myFunctions.functionDetails)
display(myFunctions.itemDetails)

# Invoke a function
myFunctions.functionName('value1', 'value2')
# Or with named parameters
myFunctions.functionName(parameter1='value1', parameter2='value2')

Ανάκτηση συναρτήσεων από UDF

myFunctions = notebookutils.udf.getFunctions('UDFItemName')
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

var myFunctions = notebookutils.udf.getFunctions("UDFItemName")
var myFunctions = notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

myFunctions <- notebookutils.udf.getFunctions("UDFItemName")
myFunctions <- notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

Κλήση συνάρτησης

myFunctions.functionName('value1', 'value2'...)

val res = myFunctions.functionName('value1', 'value2'...)

myFunctions$functionName('value1', 'value2'...)

Εμφάνιση λεπτομερειών για ένα στοιχείο UDF

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Εμφάνιση λεπτομερειών συνάρτησης για UDF

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Διαπιστευτήρια βοηθητικά προγράμματα

Μπορείτε να χρησιμοποιήσετε τα Βοηθητικά προγράμματα διαπιστευτηρίων για να λάβετε διακριτικά πρόσβασης και να διαχειριστείτε μυστικά σε ένα Azure Key Vault.

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

notebookutils.credentials.help()

Output:

Help on module notebookutils.credentials in notebookutils:

NAME
    notebookutils.credentials - Utility for credentials operations in Fabric

FUNCTIONS
    getSecret(akvName, secret) -> str
        Gets a secret from the given Azure Key Vault.
        :param akvName: The name of the Azure Key Vault.
        :param secret: The name of the secret.
        :return: The secret value.
    
    getToken(audience) -> str
        Gets a token for the given audience.
        :param audience: The audience for the token.
        :return: The token.
    
    help(method_name=None)
        Provides help for the notebookutils.credentials module or the specified method.
        
        Examples:
        notebookutils.credentials.help()
        notebookutils.credentials.help("getToken")
        :param method_name: The name of the method to get help with.

DATA
    creds = <notebookutils.notebookutils.handlers.CredsHandler.CredsHandler...

FILE
    /home/trusted-service-user/cluster-env/trident_env/lib/python3.10/site-packages/notebookutils/credentials.py

Λήψη διακριτικού

Η συνάρτηση getToken επιστρέφει ένα διακριτικό Microsoft Entra για ένα δεδομένο κοινό και όνομα (προαιρετικό). Η παρακάτω λίστα εμφανίζει τα τρέχουσα διαθέσιμα κλειδιά ακροατηρίου:

Πόρος ακροατηρίου χώρου αποθήκευσης: "χώρος αποθήκευσης"
Πόρος Power BI: "pbi"
Πόρος Azure Key Vault: "keyvault"
Πόρος Synapse RTA KQL DB: "kusto"

Εκτελέστε την ακόλουθη εντολή για να λάβετε το διακριτικό:

notebookutils.credentials.getToken('audience Key')

Εκτιμήσεις:

Τα πεδία διακριτικών με το "pbi" ως κοινό ενδέχεται να αλλάξουν με την πάροδο του χρόνου. Προς το παρόν υποστηρίζονται τα ακόλουθα πεδία.
Όταν καλείτε notebookutils.credentials.getToken("pbi")), το επιστρεφόμενο διακριτικό έχει περιορισμένο πεδίο εφαρμογής, εάν το σημειωματάριο εκτελείται σε μια κύρια υπηρεσία. Το διακριτικό δεν έχει το πλήρες εύρος υπηρεσιών Fabric. Εάν το σημειωματάριο εκτελείται με την ταυτότητα χρήστη, το διακριτικό εξακολουθεί να έχει το πλήρες πεδίο υπηρεσίας Fabric, αλλά αυτό μπορεί να αλλάξει με βελτιώσεις ασφαλείας. Για να βεβαιωθείτε ότι το διακριτικό έχει το πλήρες πεδίο υπηρεσίας Fabric, χρησιμοποιήστε έλεγχο ταυτότητας MSAL αντί για το notebookutils.credentials.getToken API. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Έλεγχος ταυτότητας με Microsoft Entra ID.
Ακολουθεί η λίστα των πεδίων που έχει το διακριτικό κατά την κλήση του notebookutils.credentials.getToken με το pbi κλειδιού ακροατηρίου κάτω από την ταυτότητα της κύριας υπηρεσίας:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All

Αποκτήστε μυστικό

Η συνάρτηση getSecret επιστρέφει έναν μυστικό κωδικό Azure Key Vault για ένα δεδομένο τελικό σημείο Azure Key Vault και ένα μυστικό όνομα, χρησιμοποιώντας διαπιστευτήρια χρήστη.

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

Μοντάρετε αρχείο και κατάργησηmount

Το Fabric υποστηρίζει τα παρακάτω σενάρια μονταρίσματος στο πακέτο Microsoft Spark Utilities. Μπορείτε να χρησιμοποιήσετε τα API mount, unmount,getMountPath() και mounts() για να συνδέσετε απομακρυσμένη αποθήκευση (ADLS Gen2) σε όλους τους κόμβους εργασίας (κόμβος προγράμματος οδήγησης και κόμβοι εργαζομένων). Αφού το σημείο μονταρίσματος χώρου αποθήκευσης είναι στη θέση του, χρησιμοποιήστε το τοπικό αρχείο API για να αποκτήσετε πρόσβαση στα δεδομένα σαν να είναι αποθηκευμένα στο τοπικό σύστημα αρχείων.

Πώς μπορείτε να μοντάρετε έναν λογαριασμό ADLS Gen2

Το παρακάτω παράδειγμα δείχνει πώς μπορείτε να μοντάρετε το Azure Data Lake Storage Gen2. Η τοποθέτηση του χώρου αποθήκευσης αντικειμένων blob και του κοινόχρηστου στοιχείου αρχείων Azure λειτουργεί παρόμοια.

Αυτό το παράδειγμα προϋποθέτει ότι έχετε έναν λογαριασμό Data Lake Storage Gen2 με το όνομα storegen2, ο οποίος έχει ένα κοντέινερ με το όνομα mycontainer στο οποίο θέλετε να προσαρτήσετε /test στην περίοδο λειτουργίας Spark του σημειωματαρίου σας.

Για να μοντάρετε το κοντέινερ που ονομάζεται mycontainer, το notebookutils πρέπει πρώτα να ελέγξει αν έχετε το δικαίωμα πρόσβασης στο κοντέινερ. Προς το παρόν, το Fabric υποστηρίζει δύο μεθόδους ελέγχου ταυτότητας για τη λειτουργία ενεργοποίησης ενεργοποίησης: accountKey και sastoken.

Μοντάρετε μέσω διακριτικού υπογραφής κοινόχρηστής πρόσβασης ή κλειδιού λογαριασμού

Το NotebookUtils υποστηρίζει τη ρητή διαβίβαση ενός κλειδιού λογαριασμού ή ενός διακριτικού υπογραφής κοινόχρηστης πρόσβασης (SAS) ως παραμέτρου για τη μονταροποίηση του προορισμού.

Για λόγους ασφαλείας, συνιστούμε να αποθηκεύετε κλειδιά λογαριασμού ή διακριτικά SAS στο Azure Key Vault (όπως δείχνει το παρακάτω στιγμιότυπο οθόνης). Στη συνέχεια, μπορείτε να τα ανακτήσετε χρησιμοποιώντας το notebookutils.credentials.getSecret API. Για περισσότερες πληροφορίες σχετικά με το Azure Key Vault, ανατρέξτε στο θέμα Πληροφορίες για τα κλειδιά λογαριασμού διαχειριζόμενου χώρου αποθήκευσης Azure Key Vault.

Δείγμα κώδικα για τη μέθοδο accountKey :

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Δείγμα κώδικα για sastoken:

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Παράμετροι τοποθέτησης:

fileCacheTimeout: Τα αντικειμένα blob αποθηκεύονται στο cache στον τοπικό φάκελο temp για 120 δευτερόλεπτα από προεπιλογή. Σε αυτό το διάστημα, το blobfuse δεν ελέγχει αν το αρχείο είναι ενημερωμένο ή όχι. Η παράμετρος μπορεί να οριστεί για αλλαγή του προεπιλεγμένου χρόνου χρονικού συνόλου. Όταν πολλά προγράμματα-πελάτες τροποποιούν αρχεία ταυτόχρονα, για να αποφεύγονται ασυνέπειες μεταξύ τοπικών και απομακρυσμένων αρχείων, συνιστούμε να μικρύνετε τον χρόνο cache ή ακόμα και να τον αλλάξετε σε 0 και να λαμβάνετε πάντα τα πιο πρόσφατα αρχεία από τον διακομιστή.
χρονικό όριο: Το χρονικό όριο της λειτουργίας μονταρίσματος είναι 120 δευτερόλεπτα από προεπιλογή. Η παράμετρος μπορεί να οριστεί για αλλαγή του προεπιλεγμένου χρόνου χρονικού συνόλου. Όταν υπάρχουν πάρα πολλοί εκτελεστές ή όταν λήγουν οι ώρες μονταρίσματος, συνιστούμε να αυξάνετε την τιμή.

Μπορείτε να χρησιμοποιήσετε αυτές τις παραμέτρους ως εξής:

notebookutils.fs.mount(
   "abfss://mycontainer@<accountname>.dfs.core.windows.net",
   "/test",
   {"fileCacheTimeout": 120, "timeout": 120}
)

Note

Για λόγους ασφάλειας, συνιστάται να αποφεύγετε την ενσωμάτωση διαπιστευτηρίων απευθείας στον κώδικα. Για την περαιτέρω προστασία των διαπιστευτηρίων σας, τυχόν μυστικά που εμφανίζονται στις εξόδους σημειωματάριου αποθηκεύονται. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Μυστική σύνταξη.

Πώς να τοποθετήσετε ένα lakehouse

Δείγμα κώδικα για την τοποθέτηση μιας λίμνης σε /<mount_name>:

notebookutils.fs.mount( 
 "abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse", 
 "/<mount_name>"
)

Πρόσβαση σε αρχεία κάτω από το σημείο μονταρίσματος χρησιμοποιώντας το notebookutils fs API

Ο κύριος σκοπός της λειτουργίας μονταρίσματος είναι να επιτρέψει στους πελάτες να έχουν πρόσβαση στα δεδομένα που είναι αποθηκευμένα σε έναν λογαριασμό απομακρυσμένου χώρου αποθήκευσης με ένα API τοπικού συστήματος αρχείων. Μπορείτε επίσης να αποκτήσετε πρόσβαση στα δεδομένα χρησιμοποιώντας το notebookutils fs API με μια μονταρισμένη διαδρομή ως παράμετρο. Αυτή η μορφή διαδρομής είναι λίγο διαφορετική.

Ας υποθέσουμε ότι έχετε μοντάρει το κοντέινερ αποθήκευσης δεδομένων Gen2 mycontainer / test χρησιμοποιώντας το API μονταρίσματος. Όταν αποκτάτε πρόσβαση στα δεδομένα με ένα API τοπικού συστήματος αρχείων, η μορφή διαδρομής είναι ως εξής:

/synfs/notebook/{sessionId}/test/{filename}

Όταν θέλετε να αποκτήσετε πρόσβαση στα δεδομένα χρησιμοποιώντας το notebookutils fs API, συνιστάται να χρησιμοποιήσετε getMountPath() για να λάβετε την ακριβή διαδρομή:

path = notebookutils.fs.getMountPath("/test")

Κατάλογοι λίστας:

notebookutils.fs.ls(f"file://{notebookutils.fs.getMountPath('/test')}")

Ανάγνωση περιεχομένου αρχείου:

notebookutils.fs.head(f"file://{notebookutils.fs.getMountPath('/test')}/myFile.txt")

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

notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")

Αρχεία πρόσβασης κάτω από το σημείο μονταρίσματος μέσω τοπικής διαδρομής

Μπορείτε εύκολα να διαβάσετε και γράψετε τα αρχεία στο σημείο μονταρίσματος χρησιμοποιώντας το τυπικό σύστημα αρχείων. Ακολουθεί ένα παράδειγμα Python:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Έλεγχος υπαρχόντων σημείων μονταρίσματος

Μπορείτε να χρησιμοποιήσετε το notebookutils.fs.mounts() API για να ελέγξετε όλες τις υπάρχουσες πληροφορίες σημείου προσάρτησης:

notebookutils.fs.mounts()

Κατάργηση του μονταρίσματος του σημείου μονταρίσματος

Χρησιμοποιήστε τον ακόλουθο κώδικα για να καταργήσετε το μοντάρισμα του σημείου προσάρτησης (/test σε αυτό το παράδειγμα):

notebookutils.fs.unmount("/test")

Γνωστοί περιορισμοί

Η τρέχουσα βάση είναι μια διαμόρφωση επιπέδου εργασίας. Σας συνιστούμε να χρησιμοποιήσετε το API προσαρτήσεων για να ελέγξετε εάν υπάρχει σημείο προσάρτησης ή δεν είναι διαθέσιμο.
Ο μηχανισμός unmount δεν εφαρμόζεται αυτόματα. Όταν ολοκληρωθεί η εκτέλεση της εφαρμογής, για να καταργήσετε το σημείο μονταρίσματος και να αποδεσμεύσετε τον χώρο στον δίσκο, πρέπει να καλέσετε ρητά ένα API unmount στον κώδικά σας. Διαφορετικά, το σημείο μονταρίσματος θα εξακολουθεί να υπάρχει στον κόμβο μετά την ολοκλήρωση της εκτέλεσης της εφαρμογής.
Η μοντάρισμα ενός λογαριασμού χώρου αποθήκευσης ADLS Gen1 δεν υποστηρίζεται.

Επιχειρήσεις κοινής ωφέλειας Lakehouse

notebookutils.lakehouse παρέχει βοηθητικά προγράμματα προσαρμοσμένα για τη διαχείριση αντικειμένων Lakehouse. Αυτά τα βοηθητικά προγράμματα σάς δίνουν τη δυνατότητα να δημιουργείτε, να λαμβάνετε, να ενημερώνετε και να διαγράφετε αντικείμενα σχεδίασης Lakehouse χωρίς προσπάθεια.

Επισκόπηση μεθόδων

Ακολουθεί μια επισκόπηση των διαθέσιμων μεθόδων που παρέχονται από notebookutils.lakehouse:

# Create a new Lakehouse artifact
create(name: String, description: String = "", definition: ItemDefinition = null, workspaceId: String = ""): Artifact

# Create Lakehouse with Schema Support
create(name: String, description: String = "", definition: {"enableSchemas": True}): Artifact

# Retrieve a Lakehouse artifact
get(name: String, workspaceId: String = ""): Artifact

# Get a Lakehouse artifact with properties
getWithProperties(name: String, workspaceId: String = ""): Artifact

# Update an existing Lakehouse artifact
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact

# Delete a Lakehouse artifact
delete(name: String, workspaceId: String = ""): Boolean 

# List all Lakehouse artifacts
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]

# List all tables in a Lakehouse artifact
listTables(lakehouse: String, workspaceId: String = "", maxResults: Int = 1000): Array[Table] 

# Starts a load table operation in a Lakehouse artifact
loadTable(loadOption: collection.Map[String, Any], table: String, lakehouse: String, workspaceId: String = ""): Array[Table]

Παραδείγματα χρήσης

Για να χρησιμοποιήσετε αποτελεσματικά αυτές τις μεθόδους, εξετάστε τα παρακάτω παραδείγματα χρήσης:

Δημιουργία ενός Lakehouse

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")
# Create Lakehouse with Schema Support
artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", {"enableSchemas": True})

Λήψη ενός Lakehouse

artifact = notebookutils.lakehouse.get("artifact_name", "optional_workspace_id")

artifact = notebookutils.lakehouse.getWithProperties("artifact_name", "optional_workspace_id")

Ενημέρωση lakehouse

updated_artifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

Διαγραφή lakehouse

is_deleted = notebookutils.lakehouse.delete("artifact_name", "optional_workspace_id")

Παράθεση lakehouses σε έναν χώρο εργασίας

artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")

Παράθεση όλων των πινάκων σε ένα Lakehouse

artifacts_tables_list = notebookutils.lakehouse.listTables("artifact_name", "optional_workspace_id")

Εκκίνηση μιας λειτουργίας πίνακα φόρτωσης σε ένα Lakehouse

notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "artifact_name", "optional_workspace_id")

Πρόσθετες πληροφορίες

Για πιο λεπτομερείς πληροφορίες σχετικά με κάθε μέθοδο και τις παραμέτρους της, χρησιμοποιήστε τη notebookutils.lakehouse.help("methodName") συνάρτηση.

Βοηθητικά προγράμματα χρόνου εκτέλεσης

Εμφάνιση των πληροφοριών περιβάλλοντος περιόδου λειτουργίας

Με notebookutils.runtime.context μπορείτε να λάβετε τις πληροφορίες περιβάλλοντος της τρέχουσας ζωντανής περιόδου λειτουργίας, συμπεριλαμβανομένου του ονόματος σημειωματάριου, της προεπιλεγμένης λίμνης, των πληροφοριών χώρου εργασίας, εάν πρόκειται για εκτέλεση διοχέτευσης κ.λπ.

notebookutils.runtime.context

Ο παρακάτω πίνακας περιγράφει τις ιδιότητες.

Parameter	Explanation
`currentNotebookName`	Το όνομα του τρέχοντος σημειωματάριου
`currentNotebookId`	Το μοναδικό αναγνωριστικό του τρέχοντος σημειωματάριου
`currentWorkspaceName`	Το όνομα του τρέχοντος χώρου εργασίας
`currentWorkspaceId`	Το αναγνωριστικό του τρέχοντος χώρου εργασίας
`defaultLakehouseName`	Το εμφανιζόμενο όνομα της προεπιλεγμένης λίμνης, εάν έχει οριστεί
`defaultLakehouseId`	Το αναγνωριστικό της προεπιλεγμένης λίμνης, εάν έχει οριστεί
`defaultLakehouseWorkspaceName`	Το όνομα χώρου εργασίας της προεπιλεγμένης λίμνης, εάν έχει οριστεί
`defaultLakehouseWorkspaceId`	Το αναγνωριστικό χώρου εργασίας της προεπιλεγμένης λίμνης, εάν έχει οριστεί
`currentRunId`	Σε μια εκτέλεση αναφοράς, το τρέχον αναγνωριστικό εκτέλεσης
`parentRunId`	Σε μια εκτέλεση αναφοράς με ένθετες εκτελέσεις, αυτό το αναγνωριστικό είναι το γονικό αναγνωριστικό εκτέλεσης
`rootRunId`	Σε μια εκτέλεση αναφοράς με ένθετες εκτελέσεις, αυτό το αναγνωριστικό είναι το ριζικό αναγνωριστικό εκτέλεσης
`isForPipeline`	Εάν η εκτέλεση είναι για μια διοχέτευση
`isReferenceRun`	Εάν η τρέχουσα εκτέλεση είναι μια εκτέλεση αναφοράς
`referenceTreePath`	Η δομή δέντρου ένθετης αναφοράς εκτελείται, η οποία χρησιμοποιείται μόνο για την ιεραρχία στιγμιότυπου στη σελίδα παρακολούθησης L2
`rootNotebookId`	(Μόνο σε εκτέλεση αναφοράς) Το αναγνωριστικό του σημειωματάριου ρίζας σε μια εκτέλεση αναφοράς.
`rootNotebookName`	(Μόνο σε εκτέλεση αναφοράς) Το όνομα του σημειωματάριου ρίζας σε μια εκτέλεση αναφοράς.
`rootWorkspaceId`	(Μόνο σε εκτέλεση αναφοράς) Το αναγνωριστικό χώρου εργασίας του σημειωματάριου ρίζας σε μια εκτέλεση αναφοράς.
`rootWorkspaceName`	(Μόνο σε εκτέλεση αναφοράς) Το όνομα του χώρου εργασίας του σημειωματάριου ρίζας σε μια εκτέλεση αναφοράς.
`activityId`	Το αναγνωριστικό εργασίας livy για την τρέχουσα δραστηριότητα
`hcRepId`	Το αναγνωριστικό REPL σε λειτουργία υψηλής ταυτόχρονης εκτέλεσης
`clusterId`	Η ταυτότητα του συμπλέγματος Synapse Spark
`poolName`	Το όνομα της ομάδας Spark που χρησιμοποιείται
`environmentId`	Το αναγνωριστικό περιβάλλοντος όπου εκτελείται η εργασία
`environmentWorkspaceId`	Το αναγνωριστικό χώρου εργασίας του περιβάλλοντος
`userId`	Το αναγνωριστικό χρήστη του τρέχοντος χρήστη
`userName`	Το όνομα χρήστη του τρέχοντος χρήστη

Διαχείριση συνεδριών

Διακοπή αλληλεπιδραστικής περιόδου λειτουργίας

Αντί να κάνετε μη αυτόματο κλικ στο κουμπί διακοπής, ορισμένες φορές είναι πιο εύκολο να διακόψετε μια αλληλεπιδραστική περίοδο λειτουργίας καλώντας ένα API στον κώδικα. Σε αυτές τις περιπτώσεις, παρέχουμε μια notebookutils.session.stop() API για την υποστήριξη διακοπής της αλληλεπιδραστικής περιόδου λειτουργίας μέσω κώδικα, η οποία είναι διαθέσιμη για scala και PySpark.

notebookutils.session.stop()

notebookutils.session.stop() API διακόπτει ασύγχρονα την τρέχουσα αλληλεπιδραστική περίοδο λειτουργίας στο παρασκήνιο. Διακόπτει επίσης τη συνεδρία Spark και δημοσιεύει πόρους που καταλαμβάνονται από την περίοδο λειτουργίας, ώστε να είναι διαθέσιμοι σε άλλες περιόδους λειτουργίας στην ίδια ομάδα.

Επανεκκίνηση του διερμηνέα Python

Το βοηθητικό πρόγραμμα notebookutils.session παρέχει έναν τρόπο επανεκκίνησης του διερμηνέα Python.

notebookutils.session.restartPython()

Εκτιμήσεις:

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

Βοηθητικά προγράμματα βιβλιοθήκης μεταβλητών

Οι βιβλιοθήκες μεταβλητών σάς επιτρέπουν να αποφύγετε τιμές στην κωδικοποίηση στον κώδικα σημειωματάριού σας. Μπορείτε να ενημερώσετε τις τιμές στη βιβλιοθήκη αντί να τροποποιήσετε τον κώδικα. Το σημειωματάριο αναφέρει τη βιβλιοθήκη μεταβλητών για την ανάκτηση αυτών των τιμών. Αυτή η προσέγγιση απλοποιεί την επαναχρησιμοποίηση κώδικα σε ομάδες και έργα, χρησιμοποιώντας μια κεντρικά διαχειριζόμενη βιβλιοθήκη.

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

notebookutils.variableLibrary.help()

Output

[Preview] notebookutils.variableLibrary is a utility to Variable Library.

Below is overview about the available methods:

get(variableReference: String): String
-> Run the variable value with type.
getLibrary(variableLibraryName: String): VariableLibrary
-> Get the variable library.
Use notebookutils.variableLibrary.help("methodName") for more info about a method.

Ορισμός της μεταβλητής στη βιβλιοθήκη μεταβλητών σας

Καθορίστε πρώτα τις μεταβλητές πριν από τη χρήση notebookutils.variableLibraryτου .

Ανάκτηση της βιβλιοθήκης μεταβλητών από το Σημειωματάριο

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

val samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

samplevl <- notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

Παράδειγμα δυναμικής χρήσης της μεταβλητής.

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv" 
df = spark.read.format("csv").option("header","true").load(file_path) 

display(df)

Πρόσβαση σε μία μόνο μεταβλητή με αναφορά

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

Note

Το notebookutils.variableLibrary API υποστηρίζει πρόσβαση μόνο σε βιβλιοθήκες μεταβλητών εντός του ίδιου χώρου εργασίας.
Η ανάκτηση βιβλιοθηκών μεταβλητών σε χώρους εργασίας δεν υποστηρίζεται σε θυγατρικά σημειωματάρια κατά τη διάρκεια μιας εκτέλεσης αναφοράς.
Ο κώδικας σημειωματάριου αναφέρεται στις μεταβλητές που ορίζονται στο ενεργό σύνολο τιμών της βιβλιοθήκης μεταβλητών.

Γνωστά προβλήματα

Όταν χρησιμοποιείτε την έκδοση χρόνου εκτέλεσης παραπάνω 1.2 και τρέχετε notebookutils.help(), τα αναφερόμενα fabricClient, PBIClient API δεν υποστηρίζονται προς το παρόν, θα είναι διαθέσιμα στο περαιτέρω. Επιπλέον, το API διαπιστευτηρίων δεν υποστηρίζεται σε σημειωματάρια Scala προς το παρόν.
Το σημειωματάριο Python δεν υποστηρίζει τα API διακοπής, επανεκκίνησης Python όταν χρησιμοποιείτε το βοηθητικό πρόγραμμα notebookutils.session για διαχείριση συνεδριών.

Ανάδραση

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

Last updated on 2025-08-16

Κοινοποίηση μέσω

NotebookUtils (πρώην MSSparkUtils) για Fabric

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

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

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

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

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

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

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

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

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

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

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

Προσάρτηση/αποπροσάρτηση καταλόγου

Βοηθητικά προγράμματα φορητών υπολογιστών

Αναφορά σημειωματάριου

Αναφορά εκτέλεσης πολλών σημειωματάριων παράλληλα

Έξοδος από ένα σημειωματάριο

Διαχείριση τεχνουργημάτων σημειωματάριου

Δημιουργία σημειωματάριου

Λήψη περιεχομένου σημειωματάριου

Ενημέρωση σημειωματάριου

Διαγραφή σημειωματάριου

Καταχώρηση σημειωματάριων σε έναν χώρο εργασίας

Βοηθητικά προγράμματα συνάρτησης δεδομένων χρήστη (UDF)

Ανάκτηση συναρτήσεων από UDF

Κλήση συνάρτησης

Εμφάνιση λεπτομερειών για ένα στοιχείο UDF

Εμφάνιση λεπτομερειών συνάρτησης για UDF

Διαπιστευτήρια βοηθητικά προγράμματα

Λήψη διακριτικού

Αποκτήστε μυστικό

Μοντάρετε αρχείο και κατάργησηmount

Πώς μπορείτε να μοντάρετε έναν λογαριασμό ADLS Gen2

Μοντάρετε μέσω διακριτικού υπογραφής κοινόχρηστής πρόσβασης ή κλειδιού λογαριασμού

Πώς να τοποθετήσετε ένα lakehouse

Πρόσβαση σε αρχεία κάτω από το σημείο μονταρίσματος χρησιμοποιώντας το notebookutils fs API

Αρχεία πρόσβασης κάτω από το σημείο μονταρίσματος μέσω τοπικής διαδρομής

Έλεγχος υπαρχόντων σημείων μονταρίσματος

Κατάργηση του μονταρίσματος του σημείου μονταρίσματος

Γνωστοί περιορισμοί

Επιχειρήσεις κοινής ωφέλειας Lakehouse

Επισκόπηση μεθόδων

Παραδείγματα χρήσης

Δημιουργία ενός Lakehouse

Λήψη ενός Lakehouse

Ενημέρωση lakehouse

Διαγραφή lakehouse

Παράθεση lakehouses σε έναν χώρο εργασίας

Παράθεση όλων των πινάκων σε ένα Lakehouse

Εκκίνηση μιας λειτουργίας πίνακα φόρτωσης σε ένα Lakehouse

Πρόσθετες πληροφορίες

Βοηθητικά προγράμματα χρόνου εκτέλεσης

Εμφάνιση των πληροφοριών περιβάλλοντος περιόδου λειτουργίας

Διαχείριση συνεδριών

Διακοπή αλληλεπιδραστικής περιόδου λειτουργίας

Επανεκκίνηση του διερμηνέα Python

Βοηθητικά προγράμματα βιβλιοθήκης μεταβλητών

Ορισμός της μεταβλητής στη βιβλιοθήκη μεταβλητών σας

Ανάκτηση της βιβλιοθήκης μεταβλητών από το Σημειωματάριο

Πρόσβαση σε μία μόνο μεταβλητή με αναφορά

Γνωστά προβλήματα

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

Ανάδραση

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