Montaje y desmontaje de archivos con NotebookUtils para Fabric

NotebookUtils admite operaciones de montaje y desmontaje de archivos mediante el paquete utilidades de Microsoft Spark. Puede usar las mountAPI , unmount, getMountPath()y mounts() para adjuntar almacenamiento remoto (ADLS Gen2, Azure Blob Storage, OneLake) a todos los nodos de trabajo (nodo de controlador y nodos de trabajo). Una vez instalado el punto de montaje de almacenamiento, utilice la API de archivos locales para acceder a los datos como si estuvieran almacenados en el sistema de archivos local.

Las operaciones de montaje son especialmente útiles cuando:

• Trabaja con librerías que esperan rutas de archivo locales.
• Necesita una semántica coherente del sistema de archivos en el almacenamiento en la nube.
• Acceda eficazmente a los accesos directos de OneLake (S3/GCS).
• Cree código portátil que funcione con varios back-end de almacenamiento.

Referencia de las API

En la tabla siguiente se resumen las API de montaje disponibles:

Métodos de autenticación

Las operaciones de montaje admiten varios métodos de autenticación. Elija el método en función del tipo de almacenamiento y los requisitos de seguridad.

Token de Microsoft Entra (predeterminado y recomendado)

La autenticación de token de Microsoft Entra utiliza la identidad del ejecutor del notebook, ya sea un usuario o un principal de servicio. No requiere credenciales explícitas en la llamada de montaje, lo que lo convierte en la opción más segura. Utilice esta opción para la conexión a Lakehouse y el almacenamiento en el área de trabajo de Fabric.

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

Clave de cuenta

Use una clave de cuenta cuando la cuenta de almacenamiento no admita la autenticación de Microsoft Entra o cuando acceda al almacenamiento externo o de terceros. Almacene las claves de cuenta en Azure Key Vault y las recupere con la notebookutils.credentials.getSecret API.

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

Token de firma de acceso compartido (SAS)

Use un token de firma de acceso compartido (SAS) para el acceso con ámbito de permiso limitado por tiempo. Esta opción es útil cuando necesita conceder acceso temporal a terceros externos. Almacene tokens de SAS en 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}
)

Montaje de una cuenta de ADLS Gen2

En el ejemplo siguiente se muestra cómo montar Azure Data Lake Storage Gen2. El montaje de Blob Storage y el recurso compartido de archivos de Azure funcionan de forma similar.

En este ejemplo se supone que tiene una cuenta de Data Lake Storage Gen2 denominada storegen2, que tiene un contenedor denominado mycontainer que desea montar en /test en la sesión de Spark de su cuaderno.

Para montar el contenedor llamado mycontainer, NotebookUtils primero debe comprobar si tiene permiso para acceder al contenedor. Actualmente, Fabric admite tres métodos de autenticación para la operación de montaje del desencadenador: token de Microsoft Entra (valor predeterminado), accountKey y sasToken.

Por motivos de seguridad, almacene las claves de cuenta o los tokens de SAS en Azure Key Vault (como se muestra en la captura de pantalla siguiente). Después, puede recuperarlos con la API notebookutils.credentials.getSecret. Para obtener más información sobre Azure Key Vault, consulte Acerca de las claves de cuenta de almacenamiento administradas de Azure Key Vault.

Código de ejemplo para el método 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}
)

Código de ejemplo para 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}
)

Parámetros de montaje

Puede ajustar el comportamiento de montaje con los siguientes parámetros opcionales en el extraConfigs mapa:

• fileCacheTimeout: los blobs se almacenan en caché en la carpeta temporal local durante 120 segundos de forma predeterminada. Durante este tiempo, blobfuse no comprueba si el archivo está actualizado. Puede establecer este parámetro para cambiar el tiempo de espera predeterminado. Cuando varios clientes modifican archivos al mismo tiempo, para evitar incoherencias entre archivos locales y remotos, acorte el tiempo de caché o establézcalo en 0 para obtener siempre los archivos más recientes del servidor.
• tiempo de espera: el tiempo de espera de la operación de montaje es de 30 segundos de forma predeterminada. Puede establecer este parámetro para cambiar el tiempo de espera predeterminado. Cuando hay demasiados ejecutores o cuando se agota el tiempo de espera de montaje, aumente el valor.

Puede usar estos parámetros de la siguiente manera:

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

Recomendaciones de configuración de caché

Elija un valor de tiempo de espera de caché en función del patrón de acceso:

Patrón de caché cero

Cuando varios clientes modifican archivos simultáneamente, use una configuración de caché cero para capturar siempre la versión más reciente del servidor:

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

Montar una casa de lago

El montaje de Lakehouse solo admite la autenticación mediante tokens de Microsoft Entra. Código de ejemplo para montar un Lakehouse en /<mount_name>:

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

Acceso a archivos en el punto de montaje mediante notebookutils fs API

Use operaciones de montaje cuando desee acceder a los datos en el almacenamiento remoto a través de una API del sistema de archivos local. También puede acceder a los datos montados mediante la notebookutils.fs API con una ruta de acceso montada, pero el formato de ruta de acceso difiere.

Supongamos que ha montado el contenedor de Data Lake Storage Gen2 mycontainer en /test utilizando la API de montaje. Cuando accede a los datos con la API del sistema de archivos local, el formato de la ruta de acceso es como el siguiente:

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

Cuando quiera acceder a los datos mediante la notebookutils fs API, use getMountPath() para obtener la ruta de acceso precisa:

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

• Listar directorios.

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

• Leer el contenido del archivo.

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

• Cree un directorio.

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

Acceder a los archivos en el punto de montaje mediante la ruta de acceso local

Puede leer y escribir archivos en un punto de montaje mediante el sistema de archivos estándar. En el ejemplo de Python siguiente se muestra este patrón:

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

Comprobación de los puntos de montaje existentes

Use la API notebookutils.fs.mounts() para comprobar toda la información de todos los puntos de montaje existentes:

notebookutils.fs.mounts()

Compruebe si existe la montura antes de montarla

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

Desmonta el punto de montaje

Use el código siguiente para desmontar el punto de montaje (/test en este ejemplo):

notebookutils.fs.unmount("/test")

Flujo de trabajo de montaje, proceso y desmontaje

Para la administración confiable de recursos, ajuste las operaciones de montaje en un try/finally bloque para asegurarse de que la limpieza se realiza incluso si ocurre un error:

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

Limitaciones conocidas

• Los montajes son configuraciones de nivel de trabajo. Use la mounts API para comprobar si ya existe un punto de montaje o está disponible.
• El desmontaje no se produce automáticamente. Cuando finalice la ejecución de la aplicación, llame a una API de desmontaje en el código para liberar espacio en disco. De lo contrario, el punto de montaje permanece en el nodo una vez finalizada la ejecución de la aplicación.
• No se admite el montaje de una cuenta de almacenamiento de ADLS Gen1.

Contenido relacionado

• NotebookUtils for Fabric
• Utilidades del sistema de archivos NotebookUtils