Montage et démontage des fichiers via NotebookUtils pour Fabric

NotebookUtils prend en charge les opérations de montage et de démontage de fichiers via le package Utilitaires Microsoft Spark. Vous pouvez utiliser les API mount, unmount, getMountPath() et mounts() pour attacher le stockage distant (ADLS Gen2, Azure Blob Storage, OneLake) à tous les nœuds de travail (nœud maître et nœuds de calcul). 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.

Les opérations de montage sont particulièrement utiles lorsque vous :

• Travaillez avec des bibliothèques qui attendent des chemins de fichiers locaux.
• Vous avez besoin d’une sémantique de système de fichiers cohérente dans le stockage cloud.
• Accédez efficacement aux raccourcis OneLake (S3/GCS).
• Générez du code portable qui fonctionne avec plusieurs back-ends de stockage.

Référence d’API

Le tableau suivant récapitule les API de montage disponibles :

Méthodes d’authentification

Les opérations de montage prennent en charge plusieurs méthodes d’authentification. Choisissez la méthode en fonction de votre type de stockage et de vos exigences de sécurité.

Jeton Microsoft Entra (par défaut et recommandé)

L’authentification par jeton Microsoft Entra utilise l’identité de l’exécuteur de notebook, qu’il s’agisse d’un utilisateur ou d’un principal de service. Il ne nécessite pas d’informations d’identification explicites dans l’appel de montage, ce qui en fait l’option la plus sécurisée. Utilisez cette option pour le montage de Lakehouse et le stockage de l'espace de travail Fabric.

# Mount using Microsoft Entra token (no credentials needed)
notebookutils.fs.mount(
    "abfss://mycontainer@mystorageaccount.dfs.core.windows.net",
    "/mydata"
)

Clé de compte

Utilisez une clé de compte lorsque le compte de stockage ne prend pas en charge l’authentification Microsoft Entra, ou lorsque vous accédez à un stockage externe ou tiers. Stockez les clés de compte dans Azure Key Vault et récupérez-les avec l’API notebookutils.credentials.getSecret .

# Retrieve account key from Azure Key Vault
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"accountKey": accountKey}
)

Jeton de signature d’accès partagé (SAP)

Utilisez un jeton de signature d’accès partagé (SAP) pour l’accès limité au temps et limité à l’autorisation. Cette option est utile lorsque vous devez accorder un accès temporaire aux parties externes. Stockez des jetons SAP dans Azure Key Vault.

# Retrieve SAS token from Azure Key Vault
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"sasToken": sasToken}
)

Monter un compte ADLS Gen2

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

Cet exemple suppose que vous disposez d’un compte Data Lake Storage Gen2 nommé storegen2, qui a 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 trois méthodes d’authentification pour l’opération de montage du déclencheur : jeton Microsoft Entra (par défaut), accountKey et sasToken.

Pour des raisons de sécurité, stockez des clés de compte ou des jetons SAP dans Azure Key Vault (comme le montre la capture d’écran suivante). 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 the full audience, such as 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 the full audience, such as 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

Vous pouvez régler le comportement de montage avec les paramètres facultatifs suivants dans la extraConfigs carte :

• 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. Vous pouvez définir ce paramètre pour modifier le délai d’expiration par défaut. Lorsque plusieurs clients modifient des fichiers en même temps, pour éviter les incohérences entre les fichiers locaux et distants, raccourcissez le temps de cache ou définissez-le sur 0 pour toujours obtenir les derniers fichiers du serveur.
• délai d’expiration : le délai d’expiration de l’opération de montage est de 30 secondes par défaut. Vous pouvez définir ce paramètre pour modifier le délai d’expiration par défaut. Lorsqu'il y a trop d'exécuteurs ou lorsque le délai du montage s'écoule, augmentez la valeur.

Vous pouvez utiliser ces paramètres comme suit :

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

Recommandations de configuration du cache

Choisissez une valeur de délai d’expiration du cache en fonction de votre modèle d’accès :

Modèle de cache zéro

Lorsque plusieurs clients modifient simultanément des fichiers, utilisez une configuration de cache zéro pour récupérer toujours la dernière version du serveur :

# For scenarios with multiple clients modifying files
# Use zero cache to always fetch the latest from the server
notebookutils.fs.mount(
    "abfss://shared@account.dfs.core.windows.net",
    "/shared_data",
    {"fileCacheTimeout": 0}
)

Monter un lakehouse

Le montage Lakehouse prend uniquement en charge l’authentification par jeton Microsoft Entra. Exemple de code pour le montage d’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

Utilisez les opérations de montage lorsque vous souhaitez accéder aux données dans le stockage distant via une API de système de fichiers local. Vous pouvez également accéder aux données montées à l’aide de l’API notebookutils.fs avec un chemin monté, mais le format de chemin diffère.

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 , utilisez cette option getMountPath() pour obtenir le chemin d’accès précis :

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

• Répertorier les répertoires.

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

• Lire le contenu du fichier.

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

• Créez 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 lire et écrire des fichiers dans un point de montage à l’aide du système de fichiers standard. L’exemple Python suivant montre ce modèle :

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

Vérifier les points de montage existants

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

notebookutils.fs.mounts()

Vérifiez si un montage existe avant le montage

existing_mounts = notebookutils.fs.mounts()
mount_point = "/mydata"

if any(m.mountPoint == mount_point for m in existing_mounts):
    print(f"Mount point {mount_point} already exists")
else:
    notebookutils.fs.mount(
        "abfss://container@account.dfs.core.windows.net",
        mount_point
    )
    print("Mount created successfully")

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

Flux de travail de montage-traitement-démontage

Pour une gestion fiable des ressources, enveloppez les opérations de montage dans un bloc try/finally pour assurer que le nettoyage se produit même si une erreur se produit.

def process_with_mount(source_uri, mount_point):
    """Complete workflow: mount, process, unmount."""
    
    try:
        # Step 1: Check if already mounted
        existing = notebookutils.fs.mounts()
        if any(m.mountPoint == mount_point for m in existing):
            print(f"Already mounted at {mount_point}")
        else:
            notebookutils.fs.mount(source_uri, mount_point)
            print(f"Mounted {source_uri} at {mount_point}")
        
        # Step 2: Process data using local file system
        mount_path = notebookutils.fs.getMountPath(mount_point)
        
        with open(f"{mount_path}/data/input.txt", "r") as f:
            data = f.read()
        
        processed = data.upper()
        
        with open(f"{mount_path}/output/result.txt", "w") as f:
            f.write(processed)
        
        print("Processing complete")
        
    finally:
        # Step 3: Always unmount to release resources
        notebookutils.fs.unmount(mount_point)
        print(f"Unmounted {mount_point}")

process_with_mount(
    "abfss://mycontainer@mystorage.dfs.core.windows.net",
    "/temp_mount"
)

Limitations connues

• Les montages sont des configurations au niveau du travail. Utilisez l’API mounts pour vérifier si un point de montage existe déjà ou est disponible.
• Le démontage ne se produit pas automatiquement. Une fois l’exécution de l’application terminée, appelez une API démontable dans votre code pour libérer de l’espace disque. Sinon, le point de montage reste sur le nœud une fois l’exécution de l’application terminée.
• Le branchement d’un compte de stockage ADLS Gen1 n’est pas supporté.

Contenu connexe

• NotebookUtils for Fabric
• Utilitaires de système de fichiers NotebookUtils