NotebookUtils (ehemalige MSSparkUtils) für Fabric

Artikel
07/26/2024

Notebook Utilities (NotebookUtils) ist ein integriertes Paket, mit dem Sie allgemeine Aufgaben in Fabric Notebook problemlos ausführen können. Sie können NotebookUtils verwenden, um mit Dateisystemen zu arbeiten, Umgebungsvariablen zu erhalten, Notebooks miteinander zu verketten und mit Geheimnissen zu arbeiten. Das NotebookUtils-Paket ist in PySpark (Python) Scala, SparkR-Notebooks und Fabric-Pipelines verfügbar.

Hinweis

MsSparkUtils wurde offiziell in NotebookUtils umbenannt. Der vorhandene Code bleibt abwärtskompatibel und verursacht keine Breaking Changes. Es wird dringend empfohlen, ein Upgrade auf NotebookUtils durchzuführen, um weiterhin Unterstützung für und Zugriff auf neue Features zu gewährleisten. Der Namespace „mssparkutils“ wird in Zukunft ausgemustert.
NotebookUtils ist für die Zusammenarbeit mit Spark 3.4 (Runtime v1.2) und höher ausgelegt. Alle neuen Features und Updates werden künftig ausschließlich mit dem Namespace „notebookutils“ unterstützt.

Dateisystem-Hilfsprogramme

notebookutils.fs stellt Hilfsprogramme für die Arbeit mit verschiedenen Dateisystemen zur Verfügung, einschließlich Azure Data Lake Storage (ADLS) Gen2 und Azure Blob Storage. Stellen Sie sicher, dass Sie den Zugriff auf Azure Data Lake Storage Gen2 und Azure Blob Storage entsprechend konfigurieren.

Führen Sie die folgenden Befehle aus, um eine Übersicht über die verfügbaren Methoden zu erhalten:

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 -> [Preview] 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 funktioniert mit dem Dateisystem auf die gleiche Weise wie Spark-APIs. Beispiel: Syntax von notebookutils.fs.mkdirs() und Fabric Lakehouse:

Verwendung	Relativer Pfad vom HDFS-Stamm	Absoluter Pfad für das ABFS-Dateisystem	Absoluter Pfad für das lokale Dateisystem auf dem Treiberknoten
Nicht-Standard-Lakehouse	Nicht unterstützt	notebookutils.fs.mkdirs("abfss://<container_name>@<speicherkonto_name.dfs.core.windows.net/>< neues_verz>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Standard-Lakehouse	Verzeichnis unter „Files“ oder „Tables“: notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://<container_name>@<speicherkonto_name.dfs.core.windows.net/>< neues_verz>")	notebookutils.fs.mkdirs("file:/<new_dir>")

Auflisten von Dateien

Zum Auflisten des Inhalts eines Verzeichnisses verwenden Sie notebookutils.fs.ls('Ihr Verzeichnispfad'). Zum Beispiel:

notebookutils.fs.ls("Files/tmp") # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # based on ABFS file system 
notebookutils.fs.ls("file:/tmp")  # based on local file system of driver node

Anzeigen von Dateieigenschaften

Diese Methode gibt Dateieigenschaften zurück, einschließlich Dateiname, Dateipfad, Dateigröße und ob es sich um ein Verzeichnis und eine Datei handelt.

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

Neues Verzeichnis erstellen

Diese Methode erstellt das angegebene Verzeichnis, wenn es nicht vorhanden ist, und alle erforderlichen übergeordneten Verzeichnisse.

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

Datei kopieren

Diese Methode kopiert eine Datei oder ein Verzeichnis und unterstützt dateisystemübergreifende Kopieraktivitäten.

notebookutils.fs.cp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Leistungsfähiges Kopieren von Dateien

Diese Methode bietet einen effizienteren Ansatz zum Kopieren oder Verschieben von Dateien, insbesondere beim Umgang mit großen Datenmengen. Für eine verbesserte Leistung auf Fabric ist es ratsam, fastcp als Ersatz für die herkömmliche cp-Methode zu verwenden.

Hinweis

notebookutils.fs.fastcp() unterstützt das Kopieren von Dateien in OneLake nicht über Regionen hinweg. In diesem Fall können Sie stattdessen notebookutils.fs.cp() verwenden.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Vorschau von Dateiinhalt anzeigen

Diese Methode gibt bis zu den ersten „maxBytes”-Bytes der angegebenen Datei als in UTF-8 codierte Zeichenfolge zurück.

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

Datei verschieben

Diese Methode verschiebt eine Datei oder ein Verzeichnis und unterstützt dateisystemübergreifende Verschiebungen.

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.

Datei schreiben

Diese Methode schreibt die angegebene Zeichenfolge in eine Datei, die in UTF-8 codiert ist.

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

Inhalt an eine Datei anfügen

Diese Methode fügt die angegebene Zeichenfolge an eine Datei an, die in UTF-8 codiert ist.

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

Hinweis

notebookutils.fs.append() und notebookutils.fs.put() unterstützen das gleichzeitige Schreiben in derselben Datei aufgrund fehlender Atomitätsgarantien nicht.
Wenn Sie die notebookutils.fs.append-API in einer for-Schleife zum Schreiben in dieselbe Datei verwenden, empfehlen wir, eine sleep-Anweisung um 0,5s~1s zwischen den wiederkehrenden Schreibvorgängen hinzuzufügen. Dies liegt daran, dass der interne flush-Vorgang der notebookutils.fs.append-API asynchron ist, sodass eine kurze Verzögerung die Datenintegrität gewährleistet.

Datei oder Verzeichnis löschen

Die Methode entfernt eine Datei oder ein Verzeichnis.

notebookutils.fs.rm('file path', True) # Set the last parameter as True to remove all files and directories recursively

Verzeichnis einbinden/Einbindung aufheben

Weitere Informationen zur detaillierten Verwendung finden Sie unter Ein- und Aushängen von Dateien.

Notebook-Utilities

Verwenden Sie die Notebook Utilities, um ein Notebook auszuführen oder ein Notebook mit einem Wert zu beenden. Führen Sie den folgenden Befehl aus, um eine Übersicht über die verfügbaren Methoden zu erhalten:

notebookutils.notebook.help()

Ausgabe:


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] -> [Preview] Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> [Preview] This method check if the DAG is correctly defined.

[Preview] 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.

Hinweis

Notebook-Dienstprogramme gelten nicht für Apache Spark-Auftragsdefinitionen (SJD).

Verweis auf ein Notizbuch

Diese Methode verweist auf ein Notebook und gibt dessen Exit-Wert zurück. Sie können Verschachtelungsfunktionsaufrufe in einem Notebook interaktiv oder in einer Pipeline ausführen. Das Notebook, auf das verwiesen wird, wird in dem Spark-Pool ausgeführt, in dem das Notebook diese Funktion aufruft.

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

Zum Beispiel:

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

Das Fabric-Notebook unterstützt auch das Verweisen auf Notebooks über mehrere Arbeitsbereiche hinweg, indem die Arbeitsbereichs-ID angegeben wird.

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

Sie können den Momentaufnahmelink der Verweisausführung in der Zellenausgabe öffnen. Die Momentaufnahme erfasst die Ergebnisse der Codeausführung und ermöglicht das einfache Debuggen einer Verweisausführung.

Hinweis

Das arbeitsbereichübergreifende Referenznotebook wird von Laufzeitversion 1.2 und höher unterstützt.
Wenn Sie die Dateien unter Notebook-Ressource verwenden, verwenden Sie notebookutils.nbResPath im referenzierten Notebook, um sicherzustellen, dass es auf denselben Ordner wie die interaktive Ausführung verweist.

Parallele Referenzausführung mehrerer Notizbücher

Wichtig

Dieses Feature befindet sich in Vorschau.

Mit der Methode notebookutils.notebook.runMultiple() können Sie mehrere Notebooks parallel oder mit einer vordefinierten topologischen Struktur ausführen. Die API verwendet einen Multithread-Implementierungsmechanismus innerhalb einer Spark-Sitzung, was bedeutet, dass die Computeressourcen vom Referenznotebook gemeinsam genutzt werden.

Mit notebookutils.notebook.runMultiple() haben Sie folgende Möglichkeiten:

Führen Sie mehrere Notebooks gleichzeitig aus, ohne darauf zu warten, dass die einzelnen Notebooks abgeschlossen sind.
Geben Sie die Abhängigkeiten und die Reihenfolge der Ausführung für Ihre Notebooks mithilfe eines einfachen JSON-Formats an.
Optimieren Sie die Verwendung von Spark Computeressourcen, und reduzieren Sie die Kosten Ihrer Fabric-Projekte.
Zeigen Sie die Momentaufnahmen der einzelnen Notebook-Ausführungsdatensätze in der Ausgabe an, und debuggen/überwachen Sie Ihre Notebookaufgaben bequem.
Ermitteln Sie den Beendenwert jeder ausführenden Aktivität und verwenden Sie diesen in nachgelagerten Aufgaben.

Sie können auch versuchen, das notebookutils.notebook.help("runMultiple") auszuführen, um das Beispiel und die detaillierte Verwendung zu finden.

Hier ist ein einfaches Beispiel für die parallele Ausführung einer Liste von Notebooks mit dieser Methode:


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

Das Ausführungsergebnis aus dem Stammnotebook lautet wie folgt:

Im Folgenden sehen Sie ein Beispiel für das Ausführen von Notebooks mit topologischer Struktur mithilfe von notebookutils.notebook.runMultiple(). Verwenden Sie diese Methode, um Notebooks einfach über eine Codeumgebung zu koordinieren.

# 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})

Das Ausführungsergebnis aus dem Stammnotebook lautet wie folgt:

Außerdem stellen wir eine Methode bereit, um zu überprüfen, ob die DAG korrekt definiert ist.

notebookutils.notebook.validateDAG(DAG)

Hinweis

Der Parallelitätsgrad der Ausführung mehrerer Notebooks ist auf die gesamte verfügbare Computeressource einer Spark-Sitzung beschränkt.
Die Obergrenze für Notebook-Aktivitäten oder gleichzeitige Notebooks beträgt 50. Eine Überschreitung dieses Grenzwerts kann zu Stabilitäts- und Leistungsproblemen führen, da eine hohe Auslastung der Computeressourcen auftritt. Wenn Probleme auftreten, sollten Sie in Erwägung ziehen, die Notebooks in mehrere runMultiple Aufrufe aufzuteilen oder die Gleichzeitigkeit zu reduzieren, indem Sie das Feld Gleichzeitigkeit im DAG-Parameter anpassen.
Die Standard-Zeitüberschreitung für die gesamte DAG beträgt 12 Stunden, und die Standard-Zeitüberschreitung für jede Zelle im untergeordneten Notebook beträgt 90 Sekunden. Sie können die Zeitüberschreitung ändern, indem Sie die Felder timeoutInSeconds und timeoutPerCellInSeconds im DAG-Parameter festlegen.

Beenden eines Notebooks

Diese Methode beendet ein Notebook mit einem Wert. Sie können Verschachtelungsfunktionsaufrufe in einem Notebook interaktiv oder in einer Pipeline ausführen.

Wenn Sie eine exit()-Funktion aus einem Notebook interaktiv aufrufen, löst das Fabric-Notebook eine Ausnahme aus, überspringt die Ausführung von nachfolgenden Zellen und behält die Spark-Sitzung bei.
Wenn Sie ein Notebook in einer Pipeline orchestrieren, die eine exit()-Funktion aufruft, gibt die Notebook-Aktivität einen Exit-Wert zurück, schließt die Pipelineausführung ab und beendet die Spark-Sitzung.
Wenn Sie eine exit()-Funktion in einem Notebook aufrufen, auf das verwiesen wird, beendet Fabric Spark die weitere Ausführung des Notebooks, auf das verwiesen wird, und fährt mit der Ausführung der nächsten Zellen im Hauptnotebook fort, das die run()-Funktion aufruft. Ein Beispiel: Notebook1 hat drei Zellen und ruft in der zweiten Zelle eine exit()-Funktion auf. Notebook2 weist fünf Zellen auf und ruft run(notebook1) in der dritten Zelle auf. Wenn Sie Notebook2 ausführen, wird Notebook1 in der zweiten Zelle beendet, sobald die exit()-Funktion erreicht wird. Notebook2 setzt die Ausführung seiner vierten Zelle und fünften Zelle fort.

notebookutils.notebook.exit("value string")

Hinweis

Die exit()-Funktion überschreibt die aktuelle Zellenausgabe, um zu vermeiden, dass die Ausgabe anderer Codeanweisungen verloren geht. Rufen Sie notebookutils.notebook.exit() in einer separaten Zelle auf.

Zum Beispiel:

Sample1-Notebook mit den beiden folgenden Zellen:

Zelle 1 definiert einen Eingabe-Parameter, dessen Standardwert auf 10 festgelegt ist.
Zelle 2 beendet das Notebook mit Eingabe als Exit-Wert.

Sie können Muster1 in einem anderen Notebook mit Standardwerten ausführen:

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

Ausgabe:

Notebook is executed successfully with exit value 10

Sie können Muster1 in einem anderen Notebook ausführen und den Eingabewert als 20 festlegen:

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

Ausgabe:

Notebook is executed successfully with exit value 20

VerwaltenA von Notebook-Artefakten

notebookutils.notebook stellt spezielle Hilfsprogramme zum programmgesteuerten Verwalten von Notebook-Ementen bereit. Diese APIs können Ihnen helfen, Notebook-Elemente auf einfache Weise zu erstellen, abzurufen, zu aktualisieren und zu löschen.

Berücksichtigen Sie die folgenden Anwendungsbeispiele, um diese Methoden effektiv zu nutzen:

Erstellen eines Notebooks

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

Abrufen von Inhalten eines Notebooks

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

Aktualisieren eines Notebooks

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

Löschen eines Notebooks

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

Auflisten von Notebooks in einem Arbeitsbereich

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

Hilfsprogramme für Anmeldeinformationen

Sie können die Hilfsprogramme für Anmeldeinformationen verwenden, um die Zugriffstoken abzurufen und Geheimnisse in einem Azure Key Vault zu verwalten.

Führen Sie den folgenden Befehl aus, um eine Übersicht über die verfügbaren Methoden zu erhalten:

notebookutils.credentials.help()

Ausgabe:

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

Abrufen von Token

getToken gibt ein Microsoft Entra-Token für eine bestimmte Zielgruppe und einen bestimmten Name (optional) zurück. Die folgende Liste zeigt die derzeit verfügbaren Zielgruppenschlüssel:

Speicher-Zielgruppenressource: „storage“
Power BI-Ressource: „pbi“
Azure Key Vault-Ressource: „keyvault“
Synapse RTA KQL DB-Ressource: „kusto“

Führen Sie den folgenden Befehl aus, um das Token abzurufen:

notebookutils.credentials.getToken('audience Key')

Geheimnis mithilfe der Benutzeranmeldeinformationen abrufen

getSecret gibt das Azure Key Vault-Geheimnis für einen angegebenen Azure Key Vault-Endpunkt und Geheimnisnamen mithilfe der Benutzeranmeldeinformationen zurück.

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

Ein- und Aushängen von Dateien

Fabric unterstützt die folgenden Einbindungsszenarien im Paket der Microsoft Spark-Hilfsprogramme. Sie können die APIs mount, unmount, getMountPath() und mounts() verwenden, um Remotespeicher (ADLS Gen2) an alle funktionierenden Knoten (Treiberknoten und Workerknoten) anzufügen. Wenn der Bereitstellungspunkt für den Speicher vorhanden ist, können Sie die lokale Datei-API verwenden, um auf Daten zuzugreifen, als ob sie im lokalen Dateisystem gespeichert wären.

Einbinden eines ADLS Gen2-Kontos

Das folgende Beispiel veranschaulicht, wie Sie Azure Data Lake Storage Gen2 einbinden. Das Einbinden von Blob Storage funktioniert ähnlich.

In diesem Beispiel wird davon ausgegangen, dass Sie über ein Data Lake Storage Gen2-Konto mit dem Namen storegen2 verfügen und das Konto über einen Container mit dem Namen mycontainer verfügt, den Sie in /test in Ihrer Spark-Notebooksitzung einbinden möchten.

Zum Einbinden des Containers namens mycontainer muss notebookutils zuerst überprüfen, ob Sie über die Berechtigung zum Zugreifen auf den Container verfügen. Derzeit unterstützt Fabric zwei Authentifizierungsmethoden für den Triggereinbindungsvorgang: accountKey und sastoken.

Einbinden über SAS-Token (Shared Access Signature) oder Kontoschlüssel

NotebookUtils unterstützt die explizite Übergabe eines Kontoschlüssels oder eines SAS-Token (Shared Access Signature) als Parameter zum Einbinden des Ziels.

Aus Sicherheitsgründen empfehlen wir, Kontoschlüssel oder SAS-Token in Azure Key Vault zu speichern (wie im folgenden Beispiel gezeigt). Sie können sie mithilfe der notebookutils.credentials.getSecret-API abrufen. Weitere Informationen zu Azure Key Vault finden Sie unter Informationen zu mit Azure Key Vault verwalteten Speicherkontoschlüsseln.

Beispielcode für die accountKey-Methode:

# 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}
)

Beispielcode für 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}
)

Einbindungsparameter:

fileCacheTimeout: Blobs werden standardmäßig 120 Sekunden lang im lokalen temporären Ordner zwischengespeichert. Während dieser Zeit prüft BlobFuse nicht, ob die Datei aktuell ist oder nicht. Der Parameter kann so festgelegt werden, dass die Standardtimeoutzeit geändert wird. Wenn mehrere Clients gleichzeitig Dateien ändern, empfiehlt es sich, die Cachezeit zu verkürzen oder sogar auf 0 zu ändern und immer die neuesten Dateien vom Server abzurufen, um Inkonsistenzen zwischen lokalen Dateien und Remotedateien zu vermeiden.
Timeout: Das Timeout des Einbindungsvorgangs beträgt standardmäßig 120 Sekunden. Der Parameter kann so festgelegt werden, dass die Standardtimeoutzeit geändert wird. Wenn zu viele Executors vorhanden sind oder bei der Einbindung ein Timeout auftritt, empfiehlt es sich, den Wert zu erhöhen.

Sie können diese Parameter wie folgt verwenden:

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

Hinweis

Aus Sicherheitsgründen wird empfohlen, das direkte Einbetten von Anmeldedaten in Code zu vermeiden. Um Ihre Anmeldedaten weiter zu schützen, werden alle geheimen Schlüssel, die in den Notebook-Ausgaben angezeigt werden, unkenntlich gemacht. Weitere Informationen finden Sie unter Geheimnisbearbeitung.

Einbinden eines Lakehouse

Beispielcode zum Einbinden eines Lakehouse in /<mount_name>:

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

Zugriff auf Dateien unter dem Bereitstellungspunkt mithilfe der notebookutils fs-API

Der Hauptzweck des Einbindungsvorgangs besteht darin, Kunden den Zugriff auf Daten zu ermöglichen, die in einem Remotespeicherkonto gespeichert sind, indem sie eine lokale Dateisystem-API verwenden. Sie können auch auf die Daten zugreifen, indem Sie die notebookutils fs-API mit einem bereitgestellten Pfad als Parameter verwenden. Dieses Pfadformat weicht davon etwas ab.

Angenommen, Sie haben den Data Lake Storage Gen2-Container mycontainer mithilfe der Bereitstellungs-API unter /test eingebunden. Wenn Sie mithilfe der lokalen Dateisystem-API auf die Daten zugreifen, sieht das Pfadformat wie folgt aus:

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

Wenn Sie mithilfe der notebookutils fs-API auf die Daten zugreifen möchten, empfiehlt es sich, getMountPath() zu verwenden, um den genauen Pfad abzurufen:

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

Auflisten von Verzeichnissen:

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

Lesen von Dateiinhalten:

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

Erstellen eines Verzeichnisses:

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

Zugreifen auf Dateien unter dem Bereitstellungspunkt über einen lokalen Pfad

Sie können die Dateien im Bereitstellungspunkt einfach mithilfe des Standarddateisystems lesen und schreiben. Hier ist ein Python-Beispiel:

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

Überprüfen vorhandener Bereitstellungspunkte

Sie können die notebookutils.fs.mounts()-API verwenden, um alle vorhandenen Bereitstellungspunktinformationen zu überprüfen:

notebookutils.fs.mounts()

Aufheben der Bereitstellung eines Bereitstellungspunkts

Verwenden Sie den folgenden Code, um Ihren Bereitstellungspunkt (/test in diesem Beispiel) aufzuheben:

notebookutils.fs.unmount("/test")

Bekannte Einschränkungen

Die aktuelle Einbindung ist eine Konfiguration auf Auftragsebene. Wir empfehlen Ihnen, die mounts-API zu verwenden, um zu überprüfen, ob der Bereitstellungspunkt vorhanden oder nicht verfügbar ist.
Der Mechanismus für die Aufhebung der Bereitstellung wird nicht automatisch angewendet. Wenn die Ausführung der Anwendung beendet ist, müssen Sie explizit eine unmount-API in Ihrem Code aufrufen, um den Bereitstellungspunkt aufzuheben und den Speicherplatz freizugeben. Andernfalls ist der Bereitstellungspunkt weiterhin im Knoten vorhanden, nachdem die Anwendungsausführung beendet wurde.
Das Einbinden eines ADLS Gen1-Speicherkontos wird nicht unterstützt.

Lakehouse-Hilfsprogramm

notebookutils.lakehouse stellt Hilfsprogramme bereit, die speziell auf die Verwaltung von Lakehouse-Elementen zugeschnitten sind. Mit diesen Hilfsprogrammen können Sie mühelos Lakehouse-Artefakte erstellen, abrufen, aktualisieren und löschen.

Übersicht über die Methoden

Im Folgenden finden Sie eine Übersicht über die verfügbaren Methoden, die von notebookutils.lakehouse bereitgestellt werden:

# Create a new Lakehouse artifact
create(name: String, description: String = "", definition: ItemDefinition = null, workspaceId: String = ""): 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]

Anwendungsbeispiele

Berücksichtigen Sie die folgenden Anwendungsbeispiele, um diese Methoden effektiv zu nutzen:

Erstellen eines Lakehouse

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")

Abrufen eines Lakehouses

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

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

Aktualisieren eines Lakehouse

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

Löschen eines Lakehouse

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

Auflisten von Lakehouses in einem Arbeitsbereich

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

Auflisten aller Tabellen in einem Lakehouse

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

Starten eines Ladetabellenvorgangs in einem 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")

Weitere Informationen

Verwenden Sie die notebookutils.lakehouse.help("methodName")-Funktion, um detailliertere Informationen zu den einzelnen Methoden und ihren Parametern zu finden.

Runtime-Dienstprogramme

Anzeigen der Sitzungskontextinformationen

Mit notebookutils.runtime.context kannst du die Kontextinformationen der aktuellen Echtzeitsitzung abrufen, einschließlich des Notebooknamens, des Standardlakehouse, der Workspaceinformation, wenn es sich um eine Pipelineausführung handelt usw.

notebookutils.runtime.context

Bekanntes Problem

Wenn Sie eine Laufzeitversion über 1.2 verwenden und notebookutils.help() ausführen, werden die aufgelisteten fabricClient- und PBIClient-APIs derzeit nicht unterstützt, werden aber in Zukunft verfügbar sein. Darüber hinaus wird die Anmeldedaten-API derzeit in Scala-Notebooks nicht unterstützt.

Freigeben über

NotebookUtils (ehemalige MSSparkUtils) für Fabric

Dateisystem-Hilfsprogramme

Auflisten von Dateien

Anzeigen von Dateieigenschaften

Neues Verzeichnis erstellen

Datei kopieren

Leistungsfähiges Kopieren von Dateien

Vorschau von Dateiinhalt anzeigen

Datei verschieben

Datei schreiben

Inhalt an eine Datei anfügen

Datei oder Verzeichnis löschen

Verzeichnis einbinden/Einbindung aufheben

Notebook-Utilities

Verweis auf ein Notizbuch

Parallele Referenzausführung mehrerer Notizbücher

Beenden eines Notebooks

VerwaltenA von Notebook-Artefakten

Erstellen eines Notebooks

Abrufen von Inhalten eines Notebooks

Aktualisieren eines Notebooks

Löschen eines Notebooks

Auflisten von Notebooks in einem Arbeitsbereich

Hilfsprogramme für Anmeldeinformationen

Abrufen von Token

Geheimnis mithilfe der Benutzeranmeldeinformationen abrufen

Ein- und Aushängen von Dateien

Einbinden eines ADLS Gen2-Kontos

Einbinden über SAS-Token (Shared Access Signature) oder Kontoschlüssel

Einbinden eines Lakehouse

Zugriff auf Dateien unter dem Bereitstellungspunkt mithilfe der notebookutils fs-API

Zugreifen auf Dateien unter dem Bereitstellungspunkt über einen lokalen Pfad

Überprüfen vorhandener Bereitstellungspunkte

Aufheben der Bereitstellung eines Bereitstellungspunkts

Bekannte Einschränkungen

Lakehouse-Hilfsprogramm

Übersicht über die Methoden

Anwendungsbeispiele

Erstellen eines Lakehouse

Abrufen eines Lakehouses

Aktualisieren eines Lakehouse

Löschen eines Lakehouse

Auflisten von Lakehouses in einem Arbeitsbereich

Auflisten aller Tabellen in einem Lakehouse

Starten eines Ladetabellenvorgangs in einem Lakehouse

Weitere Informationen

Runtime-Dienstprogramme

Anzeigen der Sitzungskontextinformationen

Bekanntes Problem

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen