NotebookUtils (ehemalige MSSparkUtils) für Fabric

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.

Note

• MsSparkUtils wird offiziell in "NotebookUtils" umbenannt. Der vorhandene Code bleibt abwärtskompatibel und verursacht keine fehlerhaften Änderungen. Es wird dringend empfohlen , ein Upgrade auf Notizbuchutils zu durchführen, um weiterhin Unterstützung und Zugriff auf neue Features sicherzustellen. 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 in Zukunft ausschließlich mit dem Notebookutils-Namespace unterstützt.

Dateisystem-Hilfsprogramme

notebookutils.fs bietet Dienstprogramme für die Arbeit mit verschiedenen Dateisystemen, 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 -> 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. Nehmen Sie beispielsweise die Verwendung von notebookutils.fs.mkdirs() und Fabric lakehouse:

Usage	Relativer Pfad vom HDFS-Stamm	Absoluter Pfad für das ABFS-Dateisystem	Absoluter Pfad für das lokale Dateisystem auf dem Treiberknoten
Nicht standardmäßiges Seehaus	Nicht unterstützt	notebookutils.fs.mkdirs("abfss://<container_name>@<speicherkonto_name.dfs.core.windows.net/>< neues_verz>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Standardseehaus	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>")

• Für das Standard-Lakehouse werden Dateipfade in Ihrem Notebook mit einem Standardtimeout für den Dateicache von 120 Sekunden bereitgestellt. Dies bedeutet, dass Dateien im lokalen temporären Ordner des Notebooks für 120 Sekunden zwischengespeichert werden, auch wenn sie aus dem Lakehouse entfernt werden. Wenn Sie die Timeoutregel ändern möchten, können Sie die Bereitstellung der standardmäßigen Lakehouse-Dateipfade aufheben und sie erneut mit unterschiedlichen fileCacheTimeout-Wert bereitstellen.

• Bei nicht standardmäßigen Lakehouse-Konfigurationen können Sie den entsprechenden fileCacheTimeout-Parameter während der Montage der Lakehouse-Pfade festlegen. Durch Festlegen des Timeouts auf 0 wird sichergestellt, dass die neueste Datei vom Lakehouse-Server abgerufen wird.

Dateien auflisten

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

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

Die notebookutils.fs.ls()-API verhält sich bei Verwendung des relativen Pfads je nach Notizbuchtyp anders.

• In einem Spark-Notebook: Der relative Pfad ist relativ zum ABFSS-Pfad des Standard-Lakehouse. Beispielsweise verweist notebookutils.fs.ls("Files") auf das Files-Verzeichnis im Standard-Lakehouse.

  Beispiel:

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

• In einem Python-Notizbuch: Der relative Pfad ist relativ zum Arbeitsverzeichnis des lokalen Dateisystems, das standardmäßig "/home/trusted-service-user/work" lautet. Daher sollten Sie den vollständigen Pfad anstelle eines relativen Pfads notebookutils.fs.ls("/lakehouse/default/Files") verwenden, um auf das Files Verzeichnis im Standard-Lakehouse zuzugreifen.

  Beispiel:

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

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. Wir legen fest recurse=True , dass alle Dateien und Verzeichnisse rekursiv kopiert werden.

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

Note

Aufgrund der Einschränkungen der OneLake-Verknüpfung empfiehlt es sich, einen eingebundenen Pfad anstelle eines ABFSS-Pfads zu verwenden, wenn Sie notebookutils.fs.cp() zum Kopieren von Daten aus der Verknüpfung vom Typ S3 oder GCS verwenden müssen.

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.

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

Considerations:

• 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.
• Aufgrund der Einschränkungen der OneLake-Verknüpfung empfiehlt es sich, einen eingebundenen Pfad anstelle eines ABFSS-Pfads zu verwenden, wenn Sie notebookutils.fs.fastcp() zum Kopieren von Daten aus der Verknüpfung vom Typ S3 oder GCS verwenden müssen.

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

Considerations:

• 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 von ca. 0,5 s bis 1 s zwischen den wiederkehrenden Schreibvorgängen hinzuzufügen. Diese Empfehlung liegt daran, dass der interne notebookutils.fs.append-Vorgang der flush-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. Wir legen fest recurse=True , dass alle Dateien und Verzeichnisse rekursiv entfernt werden.

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

Bereitstellungsverzeichnis bereitstellen/aufheben

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

Notizbuchdienstprogramme

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

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

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

Beispiel:

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

Das Fabric-Notizbuch unterstützt auch das Verweisen auf Notizbücher ü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.

Considerations:

• Das arbeitsbereichübergreifende Referenznotebook wird von Laufzeitversion 1.2 und höher unterstützt.
• Wenn Sie die Dateien unter " Notizbuchressource" verwenden, stellen notebookutils.nbResPath Sie sicher, dass sie auf denselben Ordner wie die interaktive Ausführung verweist.
• Der Verweislauf ermöglicht die Ausführung von untergeordneten Notizbüchern nur, wenn sie dasselbe Seehaus wie das übergeordnete Element verwenden, das Seehaus des Elternteils erben oder keines definiert. Die Ausführung wird blockiert, wenn das Kind ein anderes Seehaus als übergeordnetes Notizbuch angibt. Um diese Überprüfung zu umgehen, legen Sie fest useRootDefaultLakehouse: True.

Parallele Referenzausführung mehrerer Notizbücher

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 Notebook-Referenzausführung die Computeressourcen gemeinsam nutzen.

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:

Hier ist ein Beispiel für das Ausführen von Notizbüchern 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)

Considerations:

• Der Parallelitätsgrad der Ausführung mehrerer Notebooks ist auf die gesamte verfügbare Computeressource einer Spark-Sitzung beschränkt.
• Die Standardanzahl gleichzeitiger Notizbücher ist 50 für Spark-Notizbuch, während sie standardmäßig 25 für Python-Notizbuch ist. Sie können diesen Wert anpassen, aber übermäßige Parallelität kann aufgrund einer hohen Berechnungsressourcennutzung zu Stabilitäts- und Leistungsproblemen führen. Wenn Probleme auftreten, sollten Sie Notizbücher in mehrere runMultiple Aufrufe trennen oder die Parallelität reduzieren, indem Sie das Parallelitätsfeld im DAG-Parameter anpassen.
• Das Standardtimeout für die gesamte DAG-Ausführung beträgt 12 Stunden, und das Standardtimeout für jede Zelle im untergeordneten Notebook beträgt 90 Sekunden. Sie können das Timeout ä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 Notizbuch interaktiv aufrufen, löst das Fabric-Notizbuch eine Ausnahme aus, überspringt nachfolgende Zellen und hält die Spark-Sitzung aktiv.

• Wenn Sie ein Notebook in einer Pipeline koordinieren, die eine exit()-Funktion aufruft, wird die Notebookaktivität mit einem Beendigungswert zurückgegeben. Dadurch wird die Pipelineausführung abgeschlossen und die Spark-Sitzung beendet.

• Wenn Sie eine Exit()- Funktion in einem Notizbuch aufrufen, auf das verwiesen wird, beendet Fabric Spark die weitere Ausführung des referenzierten Notizbuchs und führt die nächsten Zellen im Hauptnotizbuch aus, in dem die Run() -Funktion aufgerufen wird. Beispiel: Notizbuch1 enthält drei Zellen und ruft eine Exit() -Funktion in der zweiten Zelle auf. Notizbuch2 enthält fünf Zellen und Anrufe run(notebook1) in der dritten Zelle. Wenn Sie "Notebook2" ausführen, stoppt "Notebook1" bei der zweiten Zelle beim Drücken der Exit() -Funktion. Notebook2 setzt die Ausführung seiner vierten Zelle und fünften Zelle fort.

notebookutils.notebook.exit("value string")

Note

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.

Beispiel:

Sample1-Notizbuch mit folgenden zwei Zellen:

• Zelle 1 definiert einen Eingabeparameter , wobei der Standardwert auf 10 festgelegt ist.

• Zelle 2 beendet das Notizbuch mit Eingabe als Ausgangswert.

Sie können das Beispiel1 in einem anderen Notizbuch mit Standardwerten ausführen:

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

Output:

Notebook is executed successfully with exit value 10

Sie können das Beispiel1 in einem anderen Notizbuch ausführen und den Eingabewert als 20 festlegen:

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

Output:

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

Dienstprogramme für die Benutzerdatenfunktion (UDF)

notebookutils.udf stellt Dienstprogramme bereit, die für die Integration von Notebookcode in Benutzerdatenfunktionen (User Data Functions, UDFs) entwickelt wurden. Mit diesen Dienstprogramme können Sie auf Funktionen aus einem UDF-Element innerhalb desselben Arbeitsbereichs oder in verschiedenen Arbeitsbereichen zugreifen. Anschließend können Sie Funktionen innerhalb eines UDF-Elements nach Bedarf aufrufen.

Hier sind einige Beispiele für die Verwendung der UDF-Hilfsprogramme:

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

Abrufen von Funktionen aus einem UDF-Element

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

Eine Funktion aufrufen

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

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

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

Anzeigen von Details für ein UDF-Element

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Anzeigen von Funktionsdetails für ein UDF-Element

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Anmeldeinformationsprogramme

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

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

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

Considerations:

• Tokenbereiche mit "pbi", da sich die Benutzergruppe im Laufe der Zeit ändern kann. Die folgenden Bereiche werden derzeit unterstützt.

• Wenn Sie notebookutils.credentials.getToken("pbi") aufrufen, hat das zurückgegebene Token einen begrenzten Bereich, wenn das Notizbuch unter einem Dienstprinzipal ausgeführt wird. Das Token verfügt nicht über den vollständigen Fabric-Dienstbereich. Wenn das Notizbuch unter der Benutzeridentität ausgeführt wird, weist das Token weiterhin den vollständigen Fabric-Dienstbereich auf, dies kann sich jedoch mit Sicherheitsverbesserungen ändern. Um sicherzustellen, dass das Token den vollständigen Fabric-Dienstbereich aufweist, verwenden Sie msAL-Authentifizierung anstelle der api notebookutils.credentials.getToken . Weitere Informationen finden Sie unter "Authentifizieren mit Microsoft Entra ID".

• Im Folgenden finden Sie die Liste der Bereiche, die das Token beim Aufrufen von notebookutils.credentials.getToken mit dem Benutzergruppenschlüssel pbi unter der Dienstprinzipalidentität hat:

  • Lakehouse.ReadWrite.All
  • MLExperiment.ReadWrite.All
  • MLModel.ReadWrite.All
  • Notebook.ReadWrite.All
  • SparkJobDefinition.ReadWrite.All
  • Workspace.ReadWrite.All
  • Dataset.ReadWrite.All

Geheimen Schlüssel 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 Bereitstellungs-, Unmount-, getMountPath()- und mounts() -APIs verwenden, um Remotespeicher (ADLS Gen2) an alle Arbeitsknoten (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. Die Einbindung von Blob Storage und Azure File Share funktioniert ähnlich.

In diesem Beispiel wird davon ausgegangen, dass Sie über ein Data Lake Storage Gen2-Konto mit dem Namen "storegen2" verfügen, das einen Container mit dem Namen "mycontainer " enthält, den Sie in Ihrer Spark-Sitzung ihres Notizbuchs bereitstellen möchten.

Um den Container mit dem Namen "mycontainer" zu mounten, muss notebookutils zuerst überprüfen, ob Sie über die Berechtigung zum Zugriff auf den Container verfügen. Derzeit unterstützt Fabric zwei Authentifizierungsmethoden für den Trigger-Bereitstellungsvorgang: 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 dann mithilfe der api notebookutils.credentials.getSecret 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}
)

Mount-Parameter:

• fileCacheTimeout: Blobs werden standardmäßig 120 Sekunden im lokalen temporären Ordner zwischengespeichert. Während dieser Zeit überprüft Blobfuse nicht, ob die Datei auf dem neuesten Stand ist oder nicht. Der Parameter kann so festgelegt werden, dass die Standardtimeoutzeit geändert wird. Wenn mehrere Clients Dateien gleichzeitig ändern, um Inkonsistenzen zwischen lokalen und Remotedateien zu vermeiden, empfehlen wir, die Cachezeit zu verkürzen oder sogar auf 0 zu ändern und immer die neuesten Dateien vom Server zu erhalten.
• Timeout: Der Timeout des Montagevorgangs 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}
)

Note

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

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

Zugreifen 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.

Gehen Sie davon aus, dass Sie den Data Lake Storage Gen2-Container mycontainer mithilfe der Bereitstellungs-API in /test bereitgestellt haben. 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, empfehlen wir die Verwendung von getMountPath() zum Abrufen des genauen Pfads:

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

• Verzeichnisse auflisten:

  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 api notebookutils.fs.mounts() verwenden, um alle vorhandenen Bereitstellungspunktinformationen zu überprüfen:

notebookutils.fs.mounts()

Aufheben der Bereitstellung eines Bereitstellungspunkts

Verwenden Sie den folgenden Code, um die Bereitstellung des Bereitstellungspunkts aufzuheben (/testen Sie in diesem Beispiel):

notebookutils.fs.unmount("/test")

Bekannte Einschränkungen

• Die aktuelle Bereitstellung ist eine Konfiguration auf Auftragsebene; Es wird empfohlen, die Bereitstellungs-API zu verwenden, um zu überprüfen, ob ein Bereitstellungspunkt vorhanden ist 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-Versorgungsunternehmen

notebookutils.lakehouse bietet Dienstprogramme, die 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

Hier finden Sie eine Übersicht über die verfügbaren Methoden, die von notebookutils.lakehousebereitgestellt werden:

# 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] 

Verwendungsbeispiele

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")
# Create Lakehouse with Schema Support
artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", {"enableSchemas": True})

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

In der folgenden Tabelle werden die Eigenschaften beschrieben.

Parameter	Explanation
currentNotebookName	Der Name des aktuellen Notizbuchs
currentNotebookId	Die eindeutige ID des aktuellen Notizbuchs
currentWorkspaceName	Der Name des aktuellen Arbeitsbereichs
currentWorkspaceId	Die ID des aktuellen Arbeitsbereichs
defaultLakehouseName	Der Anzeigename des Standard-Lakehouse, falls definiert
defaultLakehouseId	Die ID des Standardseehauses, falls definiert
defaultLakehouseWorkspaceName	Der Name des Standard-Lakehouse-Arbeitsbereichs, falls definiert.
defaultLakehouseWorkspaceId	Die Arbeitsbereichs-ID des Standard-Lakehouses, falls definiert
currentRunId	In einer Referenzausführung die aktuelle Ausführungs-ID
parentRunId	Bei einer Referenzausführung mit geschachtelten Läufen ist diese ID die übergeordnete Run-ID.
rootRunId	Bei einer Referenzausführung mit geschachtelten Läufen ist diese ID die Stammausführungs-ID.
isForPipeline	Gibt an, ob die Ausführung für eine Pipeline vorgesehen ist.
isReferenceRun	Ob die aktuelle Ausführung ein Referenzlauf ist.
referenceTreePath	Die Baumstruktur der geschachtelten Referenzdurchläufe wird nur für die Schnappschusshierarchie auf der L2-Überwachungsseite verwendet.
rootNotebookId	(Nur im Referenzlauf) Die ID des Stammnotizbuchs in einem Referenzlauf.
rootNotebookName	(Nur im Referenzlauf) Der Name des Stammnotizbuchs in einer Referenzausführung.
rootWorkspaceId	(Nur im Referenzlauf) Die Arbeitsbereichs-ID des Stammnotizbuchs in einem Referenzlauf.
rootWorkspaceName	(Nur im Referenzlauf) Der Arbeitsbereichsname des Stammnotizbuchs in einem Referenzlauf.
activityId	Die Livy Job ID für die aktuelle Tätigkeit
hcRepId	Die REPL-ID im Modus für hohe Parallelität
clusterId	Die Identität des Synapse Spark-Clusters
poolName	Der Name des verwendeten Spark-Pools
environmentId	Die Umgebungs-ID, in der der Auftrag ausgeführt wird
environmentWorkspaceId	Die Arbeitsbereichs-ID der Umgebung
userId	Die Benutzer-ID des aktuellen Benutzers
userName	Der Benutzername des aktuellen Benutzers

Sitzungsverwaltung

Beenden einer interaktiven Sitzung

Anstatt manuell auf die Stoppschaltfläche zu klicken, ist es manchmal praktischer, eine interaktive Sitzung zu beenden, indem sie eine API im Code aufruft. Für solche Fälle stellen wir eine API notebookutils.session.stop() bereit, um das Beenden der interaktiven Sitzung über Code zu unterstützen, es ist für Scala und PySpark verfügbar.

notebookutils.session.stop()

notebookutils.session.stop()-API beendet die aktuelle interaktive Sitzung asynchron im Hintergrund. Außerdem wird die Spark-Sitzung beendet und die von der Sitzung belegten Ressourcen freigegeben, sodass sie für andere Sitzungen im selben Pool verfügbar sind.

Starten Sie den Python-Dolmetscher neu

notebookutils.session utility bietet eine Möglichkeit, den Python-Interpreter neu zu starten.

notebookutils.session.restartPython()

Considerations:

• Im Fall der Notizbuchverweisausführung startet restartPython() nur den Python-Interpreter des aktuellen Notizbuchs neu, auf das verwiesen wird.
• In seltenen Fällen kann der Befehl aufgrund des Spark-Spiegelungsmechanismus fehlschlagen, durch das Hinzufügen von Wiederholungen kann das Problem behoben werden.

Variable Bibliotheks-Hilfsprogramme

Note

"Dienstprogramme der Variable-Bibliothek" in Notizbüchern befindet sich in der Vorschau.

Mit Variablenbibliotheken können Sie hartcodierende Werte in Ihrem Notizbuchcode vermeiden. Sie können die Werte in der Bibliothek aktualisieren, anstatt den Code zu ändern. Das Notizbuch verweist auf die Variable-Bibliothek, um diese Werte abzurufen. Dieser Ansatz vereinfacht die Wiederverwendung von Code in Teams und Projekten, indem eine zentral verwaltete Bibliothek verwendet wird.

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

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.

Definieren der Variablen in der Variablenbibliothek

Definieren Sie die Variablen zuerst vor der Verwendung notebookutils.variableLibrary.

Abrufen der Variablenbibliothek aus dem Notizbuch

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

Beispiel für die dynamische Verwendung der Variablen.

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) 

Zugriff auf eine einzelne Variable über Referenz

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

• Die notebookutils.variableLibrary API unterstützt nur den Zugriff auf Variablenbibliotheken innerhalb desselben Arbeitsbereichs.
• Das Abrufen von Variablenbibliotheken über Arbeitsbereiche hinweg ist während eines Referenzdurchlaufs in untergeordneten Notizbüchern nicht möglich.
• Der Notizbuchcode verweist auf die variablen, die im aktiven Wertsatz der Variablenbibliothek definiert sind.

Bekannte Probleme

• Wenn Sie die Laufzeitversion über 1.2 verwenden und ausführennotebookutils.help(), werden die aufgeführten fabricClient-PBIClient-APIs derzeit nicht unterstützt. Darüber hinaus wird die Anmeldeinformations-API derzeit in Scala-Notizbüchern nicht unterstützt.

• Das Python-Notizbuch unterstützt den Stopp nicht, starten SiePython-APIs neu, wenn Sie das Hilfsprogramm notebookutils.session für die Sitzungsverwaltung verwenden.

• Derzeit wird SPN für Hilfsprogramme für variable Bibliotheken nicht unterstützt.

Verwandte Inhalte

• Microsoft Spark-Hilfsprogramme (MSSparkUtils) für Fabric
• Entwickeln, Ausführen und Verwalten von Notebooks in Microsoft Fabric
• Verwalten und Ausführen von Notebooks in Fabric mit APIs