NotebookUtils (anciennement MSSparkUtils) pour Fabric

Article
07/26/2024

Notebook Utilities (NotebookUtils) est un package intégré pour vous aider à effectuer facilement des tâches courantes dans un notebook Fabric. Vous pouvez utiliser NotebookUtils pour travailler efficacement avec des systèmes de fichiers, pour récupérer des variables d’environnement, enchaîner des notebooks et utiliser des secrets. Le package NotebookUtils est disponible dans PySpark (Python) Scala, les notebooks SparkR et les pipelines Fabric.

Remarque

MsSparkUtils a été officiellement renommé NotebookUtils. Le code existant conservera sa compatibilité descendante et n'entraînera pas de changements cassants. Il est fortement recommandé de procéder à un changement de niveau vers notebookutils afin d'assurer un support continu et l'accès aux nouvelles fonctionnalités. L’espace de noms mssparkutils sera supprimé à l’avenir.
NotebookUtils est conçu pour fonctionner avec Spark 3.4(Runtime v1.2) et les versions ultérieures. Toutes les nouvelles fonctionnalités et mises à jour seront exclusivement supportées par l'espace de noms notebookutils à l'avenir.

Utilitaires du système de fichiers

notebookutils.fs fournit des utilitaires pour travailler avec différents systèmes de fichiers, notamment Azure Data Lake Storage (ADLS) Gen2 et Stockage Blob Azure. Veillez à configurer l’accès à Azure Data Lake Storage Gen2 et Stockage Blob Azure de manière appropriée.

Exécutez les commandes suivantes pour obtenir une vue d’ensemble des méthodes disponibles :

notebookutils.fs.help()

Sortie

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 fonctionne avec le système de fichiers de la même façon que les API Spark. Prenons l’utilisation de notebookutils.fs.mkdirs() et Fabric Lakehouse, par exemple :

Utilisation	Chemin d’accès relatif à partir de la racine HDFS	Chemin d’accès absolu pour le système de fichiers ABFS	Chemin d’accès absolu pour le système de fichiers local dans le nœud de pilote
Lakehouse autre que par défaut	Non pris en charge	notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Lakehouse par défaut	Répertoire sous « Files » ou « Tables » : notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")

Répertorier des fichiers

Pour répertorier le contenu d’un répertoire, utilisez notebookutils.fs.ls(’Le chemin d’accès à votre répertoire’). Par exemple :

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

Affichez les propriétés de fichier

Cette méthode retourne les propriétés du fichier, notamment le nom du fichier, son chemin d’accès, sa taille, s’il s’agit d’un répertoire et s’il s’agit d’un fichier.

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

Créer un répertoire

Cette méthode crée le répertoire donné s’il n’existe pas, ainsi que les répertoires parents nécessaires.

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

Copier un fichier

Cette méthode copie un fichier ou un répertoire et prend en charge l’activité de copie entre les systèmes de fichiers.

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

Fichier de copie performant

Cette méthode offre une approche plus efficace de la copie ou du déplacement de fichiers, en particulier lors du traitement de grands volumes de données. Pour améliorer les performances sur Fabric, il est conseillé d’utiliser fastcp comme substitut de la méthode cp traditionnelle.

Remarque

notebookutils.fs.fastcp() ne prend pas en charge la copie de fichiers dans OneLake entre les régions. Dans ce cas, vous pouvez utiliser notebookutils.fs.cp() à la place.

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

Afficher un aperçu du contenu du fichier

Cette méthode renvoie jusqu’aux premiers octets « maxBytes » du fichier donné sous la forme d’une chaîne encodée au format UTF-8.

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

Déplacer un fichier

Cette méthode déplace un fichier ou un répertoire et prend en charge les déplacements entre les systèmes de fichiers.

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.

Écrire dans un fichier

Cette méthode écrit la chaîne donnée dans un fichier encodé au format 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

Ajouter du contenu à un fichier

Cette méthode ajoute la chaîne donnée à un fichier, encodé au format 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

Remarque

notebookutils.fs.append() et notebookutils.fs.put() ne prennent pas en charge l’écriture simultanée dans le même fichier en raison d’un manque de garanties d’atomicité.
Lors de l’utilisation de l’API notebookutils.fs.append dans une boucle for pour écrire dans le même fichier, nous vous recommandons d’ajouter une instruction sleep d’environ 0,5 à 1 seconde entre les écritures périodiques. La raison en est que l’opération flush interne de l’API notebookutils.fs.append est asynchrone : un court retard permet donc de veiller à l’intégrité des données.

Supprimer un fichier ou un répertoire

Cette méthode déplace un fichier ou un répertoire.

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

Monter/démonter le répertoire

Pour plus d’informations sur l’utilisation détaillée dans Montage de fichiers et démonter.

Utilitaires de notebook

Utilisez les utilitaires de notebook pour exécuter un notebook ou quitter un notebook avec une valeur. Exécutez la commande suivante pour obtenir une vue d’ensemble des méthodes disponibles :

notebookutils.notebook.help()

Sortie :


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.

Remarque

Les utilitaires de notebook ne s’appliquent pas aux définitions de travail Apache Spark (SJD).

Référencer un notebook

Cette méthode référence un notebook et renvoie sa valeur de sortie. Vous pouvez exécuter des appels de fonction d’imbrication dans un notebook de manière interactive ou dans un pipeline. Le notebook référencé s’exécute sur le pool Spark du notebook qui appelle cette fonction.

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

Par exemple :

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

Le notebook Fabric prend également en charge le référencement de blocs-notes sur plusieurs espaces de travail en spécifiant l’ID de l’espace de travail.

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

Vous pouvez ouvrir le lien d’instantané de l’exécution de référence dans la sortie de cellule. L’instantané capture les résultats de l’exécution du code et vous permet de déboguer facilement une exécution de référence.

Remarque

Le notebook de référence inter-espaces de travail est pris en charge par le runtime version 1.2 et ultérieure.
Si vous utilisez les fichiers sous Ressource notebook, utilisez notebookutils.nbResPath dans le notebook référencé pour vous assurer qu’il pointe vers le même dossier que l’exécution interactive.

Exécution de référence de plusieurs notebooks en parallèle

Important

Cette fonctionnalité est en version préliminaire.

La méthode notebookutils.notebook.runMultiple() vous permet d’exécuter plusieurs notebooks en parallèle ou avec une structure topologique prédéfinie. L’API utilise un mécanisme d’implémentation multithread au sein d’une session Spark, ce qui signifie que les ressources de calcul sont partagées par les exécutions du notebook de référence.

Avec notebookutils.notebook.runMultiple(), vous pouvez :

Exécutez plusieurs notebooks simultanément, sans attendre que chacun d’eux se termine.
Spécifiez les dépendances et l’ordre d’exécution de vos notebooks à l’aide d’un format JSON simple.
Optimisez l’utilisation des ressources de calcul Spark et réduisez le coût de vos projets Fabric.
Affichez les instantanés de chaque enregistrement d’exécution de notebook dans la sortie, et déboguez/surveillez vos tâches de notebook de manière pratique.
Obtenez la valeur de sortie de chaque activité exécutive et utilisez-les dans les tâches en aval.

Vous pouvez également essayer d’exécuter notebookutils.notebook.help("runMultiple") pour rechercher l’exemple et l’utilisation détaillée.

Voici un exemple simple d’exécution d’une liste de notebooks en parallèle à l’aide de cette méthode :


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

Le résultat d’exécution du notebook racine est le suivant :

Voici un exemple d’exécution de notebooks avec une structure topologique à l’aide de notebookutils.notebook.runMultiple(). Utilisez cette méthode pour orchestrer facilement les notebooks via une expérience de code.

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

Le résultat d’exécution du notebook racine est le suivant :

Nous fournissons également une méthode pour vérifier si le DAG est correctement défini.

notebookutils.notebook.validateDAG(DAG)

Remarque

Le degré de parallélisme de l’exécution de plusieurs notebooks est limité au nombre total de ressources de calcul disponibles d’une session Spark.
La limite supérieure pour les activités de notebook ou les notebooks simultanés est de 50. Le dépassement de cette limite peut entraîner des problèmes de stabilité et de performances en raison d’une utilisation élevée des ressources de calcul. Si des problèmes se produisent, envisagez de séparer les notebooks en plusieurs appels runMultiple ou de réduire la concurrence en ajustant le champ d’accès concurrence dans le paramètre DAG.
Le délai d’expiration par défaut pour l’ensemble du DAG est de 12 heures et le délai d’expiration par défaut pour chaque cellule de notebook enfant est de 90 secondes. Vous pouvez modifier le délai d’expiration en définissant les champs timeoutInSeconds et timeoutPerCellInSeconds dans le paramètre DAG.

Quitter un notebook

Cette méthode quitte un notebook avec une valeur. Vous pouvez exécuter des appels de fonction d’imbrication dans un notebook de manière interactive ou dans un pipeline.

Lorsque vous appelez une fonction exit() à partir d’un notebook de manière interactive, le notebook Fabric lève une exception, ignore l’exécution des cellules de la sous-séquence et maintient la session Spark active.
Lorsque vous orchestrez un notebook qui appelle une fonction exit(), l’activité de notebook renvoie une valeur de sortie, termine l’exécution du pipeline et arrête la session Spark.
Lorsque vous appelez une fonction exit() dans un notebook référencé, Fabric Spark arrête l’exécution supplémentaire dans le notebook référencé et continue à exécuter les cellules suivantes du notebook principal qui appelle la fonction run(). Par exemple : Notebook1 possède trois cellules et appelle une fonction exit() dans la deuxième cellule. Notebook2 possède cinq cellules et appelle run(notebook1) dans la troisième cellule. Lorsque vous exécutez Notebook2, Notebook1 s’arrête à la deuxième cellule lorsque vous atteignez la fonction exit(). Notebook2 continue à exécuter ses quatrième et cinquième cellules.

notebookutils.notebook.exit("value string")

Remarque

La fonction exit() remplace la sortie de la cellule active. Pour éviter de perdre la sortie d’autres instructions de code, appelez notebookutils.notebook.exit() dans une cellule distincte.

Par exemple :

Le notebook Sample1 avec les deux cellules suivantes :

La cellule 1 définit un paramètre d’entrée dont la valeur par défaut est définie sur 10.
La cellule 2 quitte le notebook avec l'entrée comme valeur de sortie.

Vous pouvez exécuter Sample1 dans un autre bloc-notes avec les valeurs par défaut :

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

Output:

Notebook is executed successfully with exit value 10

Vous pouvez exécuter Sample1 dans un autre notebook et définir la valeur d’entrée sur 20 :

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

Sortie :

Notebook is executed successfully with exit value 20

Gérer les artefacts de notebook

notebookutils.notebook fournit des utilitaires spécialisés pour gérer les éléments de notebook par programmation. Ces API peuvent vous aider à créer, obtenir, mettre à jour et supprimer facilement des éléments de notebook.

Pour utiliser efficacement ces méthodes, tenez compte des exemples d’utilisation suivants :

Création d’un notebook

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

Obtention du contenu d’un notebook

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

Mise à jour d’un notebook

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

Suppression d’un notebook

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

Répertorier des notebooks dans un espace de travail

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

Utilitaires d’informations d’identification

Vous pouvez utiliser les utilitaires d’informations d’identification pour récupérer les jetons d’accès et gérer les secrets dans Azure Key Vault.

Exécutez la commande suivante pour obtenir une vue d’ensemble des méthodes disponibles :

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

Obtenir un jeton

getToken renvoie un jeton Microsoft Entra pour une audience et un nom donnés (facultatif). La liste suivante présente les touches d’audience actuellement disponibles :

Ressource d’audience de stockage : « storage »
Ressource Power BI : « pbi »
Ressource Azure Key Vault : « keyvault »
Ressource de base de données KQL Synapse RTA : « kusto »

Exécutez la commande suivante pour obtenir le jeton :

notebookutils.credentials.getToken('audience Key')

Obtenir le secret à l’aide des informations d’identification de l’utilisateur

getSecret renvoie un secret Azure Key Vault pour un point de terminaison Azure Key Vault donné et un nom de secret à l’aide des informations d’identification d’utilisateur.

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

Montage et démontage de fichiers

Fabric prend en charge les scénarios de montage suivants dans le package Utilitaires Microsoft Spark. Vous pouvez utiliser les API mount, unmount, getMountPath() et mounts() pour attacher un stockage distant (ADLS Gen2) à tous les nœuds de travail (nœud pilote et nœuds Worker). Une fois le point de montage de stockage en place, utilisez l’API de fichier local pour accéder aux données comme si elles étaient stockées dans le système de fichiers local.

Guide pratique pour monter un compte ADLS Gen2

L’exemple suivant illustre comment monter Azure Data Lake Storage Gen2. Le montage de Stockage Blob fonctionne de la même façon.

Cet exemple suppose que vous disposez d’un compte Data Lake Storage Gen2 nommé storegen2et que le compte possède un conteneur nommé mycontainer que vous souhaitez monter sur /test dans votre session Spark de notebook.

Pour monter le conteneur appelé mycontainer, notebookutils doit d’abord vérifier si vous disposez de l’autorisation d’accéder au conteneur. Actuellement, Fabric prend en charge deux méthodes d’authentification pour l’opération de montage du déclencheur : accountKey et sastoken.

Montage via un jeton de signature d’accès partagé ou une clé de compte

NotebookUtils prend en charge la transmission explicite d’une clé de compte ou d’un jeton de signature d’accès partagé (SAP) en tant que paramètre pour monter la cible.

Pour des raisons de sécurité, nous vous recommandons de stocker des clés de compte ou des jetons SAP dans Azure Key Vault (comme l’illustre la capture d’écran suivant). Vous pouvez ensuite les récupérer à l’aide de l’API notebookutils.credentials.getSecret. Pour plus d’informations sur Azure Key Vault, consultez À propos des clés de compte de stockage managées Azure Key Vault.

Exemple de code pour la méthode 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}
)

Exemple de code pour 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}
)

Paramètres de montage :

fileCacheTimeout : les objets blob sont mis en cache dans le dossier temporaire local pendant 120 secondes par défaut. Pendant ce temps, blobfuse ne vérifie pas si le fichier est à jour ou non. Le paramètre peut être défini pour modifier le délai d’expiration par défaut. Lorsque plusieurs clients modifient des fichiers en même temps, afin d’éviter les incohérences entre les fichiers locaux et distants, nous vous recommandons de raccourcir le temps de mise en cache, ou même de le remplacer par 0, et de toujours obtenir les derniers fichiers à partir du serveur.
timeout : le délai d’expiration de l’opération de montage est de 120 secondes par défaut. Le paramètre peut être défini pour modifier le délai d’expiration par défaut. Lorsqu’il y a trop d’exécuteurs ou lorsque le montage expire, nous vous recommandons d’augmenter la valeur.

Vous pouvez utiliser ces paramètres comme suit :

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

Remarque

À des fins de sécurité, il est recommandé de ne pas incorporer d’informations d’identification directement dans le code. Pour protéger davantage vos informations d’identification, tous les secrets affichés dans les sorties du notebook seront supprimés. Pour plus d’informations, consultez Suppression des secrets.

Guide pratique pour monter un lakehouse

Exemple de code de montage pour un lakehouse sur /<mount_name> :

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

Accéder aux fichiers sous le point de montage à l’aide de l’API notebookutils fs

L’objectif principal de l’opération de montage est de permettre aux clients d’accéder aux données stockées dans un compte de stockage distant avec une API de système de fichiers local. Vous pouvez également accéder aux données à l’aide de l’API notebookutils fs avec un chemin d’accès monté en tant que paramètre. Le format de chemin d’accès utilisé ici est un peu différent.

Supposons que vous avez monté le conteneur Data Lake Storage Gen2 mycontainer sur /test à l’aide de l’API mount. Lorsque vous accédez aux données avec l’API de système de fichiers local, le format du chemin d’accès est le suivant :

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

Lorsque vous souhaitez accéder aux données à l’aide de l’API notebookutils fs, nous vous recommandons d’utiliser un getMountPath() pour obtenir le chemin d’accès précis :

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

Lister des répertoires :

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

Lisez le contenu du fichier :

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

Créer un répertoire :

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

Accéder aux fichiers sous le point de montage via le chemin d’accès local

Vous pouvez facilement lire et écrire les fichiers au point de montage à l’aide du système de fichiers standard. Voici un exemple 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"))

Guide pratique pour vérifier les points de montage existants

Vous pouvez utiliser l’API notebookutils.fs.mounts() pour vérifier toutes les informations de point de montage existantes :

notebookutils.fs.mounts()

Comment démonter le point de montage

Utilisez le code suivant pour démonter votre point de montage (/test dans cet exemple) :

notebookutils.fs.unmount("/test")

Limitations connues

Le montage actuel étant une configuration au niveau du travail, nous vous recommandons d’utiliser l’API mounts pour vérifier si un point de montage existe ou n’est pas disponible.
Le mécanisme de démontage n’est pas automatiquement appliqué. Une fois l’exécution de l’application terminée, pour démonter le point de montage et libérer l’espace disque, vous devez appeler explicitement une API de démontage dans votre code. Sinon, le point de montage existera toujours dans le nœud une fois l’exécution de l’application terminée.
Le montage d’un compte de stockage ADLS Gen1 n’est pas pris en charge.

Utilitaires Lakehouse

notebookutils.lakehouse fournit des utilitaires spécifiquement adaptés à la gestion des éléments Lakehouse. Ces utilitaires vous permettent de créer, récupérer, mettre à jour et supprimer facilement des artefacts Lakehouse.

Vue d’ensemble des méthodes

Voici une vue d’ensemble des méthodes disponibles fournies par notebookutils.lakehouse :

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

Exemples d'utilisation

Pour utiliser efficacement ces méthodes, tenez compte des exemples d’utilisation suivants :

Création d’un Lakehouse

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

Récupérer un lakehouse

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

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

Mise à jour d’un lakehouse

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

Suppression d’un lakehouse

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

Répertorier les lakehouses dans un espace de travail

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

Répertorier toutes les tables d’un lakehouse

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

Démarrer une opération de chargement de table dans un 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")

Informations supplémentaires

Pour plus d’informations sur chaque méthode et ses paramètres, utilisez la fonction notebookutils.lakehouse.help("methodName").

Utilitaires de runtime

Afficher les informations de contexte de la session

Avec notebookutils.runtime.context, vous pouvez obtenir les informations contextuelles sur la session actuelle, notamment le nom du notebook, le lakehouse par défaut, les informations de l’espace de travail, s’il s’agit d’une exécution de pipeline, etc.

notebookutils.runtime.context

Problème connu

Lors de l’utilisation d’une version de runtime supérieure à la version 1.2 et exécutant notebookutils.help(), les API fabricClient et PBIClient répertoriées ne sont pas prises en charge pour l’instant, mais le seront disponibles plus tard. En outre, l’API Credentials n’est pas prise en charge dans les notebooks Scala à l’heure actuelle.

Partager via

NotebookUtils (anciennement MSSparkUtils) pour Fabric

Utilitaires du système de fichiers

Répertorier des fichiers

Affichez les propriétés de fichier

Créer un répertoire

Copier un fichier

Fichier de copie performant

Afficher un aperçu du contenu du fichier

Déplacer un fichier

Écrire dans un fichier

Ajouter du contenu à un fichier

Supprimer un fichier ou un répertoire

Monter/démonter le répertoire

Utilitaires de notebook

Référencer un notebook

Exécution de référence de plusieurs notebooks en parallèle

Quitter un notebook

Gérer les artefacts de notebook

Création d’un notebook

Obtention du contenu d’un notebook

Mise à jour d’un notebook

Suppression d’un notebook

Répertorier des notebooks dans un espace de travail

Utilitaires d’informations d’identification

Obtenir un jeton

Obtenir le secret à l’aide des informations d’identification de l’utilisateur

Montage et démontage de fichiers

Guide pratique pour monter un compte ADLS Gen2

Montage via un jeton de signature d’accès partagé ou une clé de compte

Guide pratique pour monter un lakehouse

Accéder aux fichiers sous le point de montage à l’aide de l’API notebookutils fs

Accéder aux fichiers sous le point de montage via le chemin d’accès local

Guide pratique pour vérifier les points de montage existants

Comment démonter le point de montage

Limitations connues

Utilitaires Lakehouse

Vue d’ensemble des méthodes

Exemples d'utilisation

Création d’un Lakehouse

Récupérer un lakehouse

Mise à jour d’un lakehouse

Suppression d’un lakehouse

Répertorier les lakehouses dans un espace de travail

Répertorier toutes les tables d’un lakehouse

Démarrer une opération de chargement de table dans un lakehouse

Informations supplémentaires

Utilitaires de runtime

Afficher les informations de contexte de la session

Problème connu

Contenu connexe

Commentaires

Ressources supplémentaires