Montaggio e smontaggio di file NotebookUtils per Fabric

NotebookUtils supporta operazioni di montaggio e smontaggio dei file tramite il pacchetto Utilità Di Microsoft Spark. È possibile usare le API mount, unmount, getMountPath() e mounts() per collegare l'archiviazione remota (ADLS Gen2, Archiviazione BLOB di Azure, OneLake) a tutti i nodi di lavoro (nodo driver e nodi di lavoro). Dopo aver creato il punto di montaggio della memoria, utilizzare l'API dei file locali per accedere ai dati come se fossero archiviati nel file system locale.

Le operazioni di montaggio sono particolarmente utili quando si:

• Usare le librerie che prevedono percorsi di file locali.
• È necessaria una semantica coerente del file system nell'archiviazione cloud.
• Accedere in modo efficiente ai collegamenti OneLake (S3/GCS).
• Compilare codice portabile che funziona con più back-end di archiviazione.

Informazioni di riferimento sulle API

La tabella seguente riepiloga le API di montaggio disponibili:

Metodi di autenticazione

Le operazioni di montaggio supportano diversi metodi di autenticazione. Scegliere il metodo in base al tipo di archiviazione e ai requisiti di sicurezza.

Token Microsoft Entra (impostazione predefinita e consigliata)

L'autenticazione del token Microsoft Entra utilizza l'identità dell'esecutore del notebook, sia esso un utente o un principale del servizio. Non richiede credenziali esplicite nella chiamata di montaggio, che lo rende l'opzione più sicura. Usare questa opzione per il montaggio di Lakehouse e lo spazio di archiviazione dell'area di lavoro Fabric.

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

Chiave dell'account

Usare una chiave dell'account quando l'account di archiviazione non supporta l'autenticazione di Microsoft Entra o quando si accede all'archiviazione esterna o di terze parti. Archiviare le chiavi dell'account in Azure Key Vault e recuperarle con 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}
)

Token di firma di accesso condiviso

Usare un token di firma di accesso condiviso (SAS) per l'accesso con ambito di autorizzazione limitato a tempo. Questa opzione è utile quando è necessario concedere l'accesso temporaneo alle parti esterne. Archiviare i token di firma di accesso condiviso in 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}
)

Montare un account ADLS Gen2

L'esempio seguente illustra come montare Azure Data Lake Storage Gen2. Il montaggio dell'archiviazione BLOB e della condivisione file di Azure funziona in modo analogo.

Questo esempio presuppone che sia presente un account Data Lake Storage Gen2 denominato storegen2, che ha un contenitore denominato mycontainer che si vuole montare in /test nella sessione spark del notebook.

Per montare il contenitore denominato mycontainer, NotebookUtils deve prima verificare se si dispone dell'autorizzazione per accedere al contenitore. Attualmente Fabric supporta tre metodi di autenticazione per l'operazione di montaggio del trigger: token Microsoft Entra (impostazione predefinita), accountKey e sasToken.

Per motivi di sicurezza, archiviare le chiavi dell'account o i token di firma di accesso condiviso in Azure Key Vault (come illustrato nello screenshot seguente). È quindi possibile recuperarli usando l'API notebookutils.credentials.getSecret . Per altre informazioni su Azure Key Vault, vedere Informazioni sulle chiavi dell'account di archiviazione gestito di Azure Key Vault.

Codice di esempio per il metodo 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}
)

Codice di esempio per 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}
)

Parametri di montaggio

È possibile ottimizzare il comportamento di montaggio con i parametri facoltativi seguenti nella extraConfigs mappa:

• fileCacheTimeout: i BLOB vengono memorizzati nella cache nella cartella temporanea locale per 120 secondi per impostazione predefinita. Durante questo periodo blobfuse non controlla se il file è aggiornato. È possibile impostare questo parametro per modificare il timeout predefinito. Quando più client modificano contemporaneamente i file, per evitare incoerenze tra file locali e remoti, abbreviare il tempo di cache o impostarlo su 0 per ottenere sempre i file più recenti dal server.
• timeout: il timeout dell'operazione di montaggio è di 30 secondi per impostazione predefinita. È possibile impostare questo parametro per modificare il timeout predefinito. Quando ci sono troppi esecutori o quando il tempo di montaggio scade, aumentare il valore.

È possibile usare questi parametri come indicato di seguito:

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

Raccomandazioni sulla configurazione della cache

Scegliere un valore di timeout della cache in base al modello di accesso:

Modello zero-cache

Quando più client modificano contemporaneamente i file, usare una configurazione zero-cache per recuperare sempre la versione più recente dal server:

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

Implementare un lakehouse

Il montaggio di Lakehouse supporta solo l'autenticazione tramite token Microsoft Entra. Codice di esempio per il montaggio di un Lakehouse su /<mount_name>:

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

Accedere ai file nel punto di montaggio usando l'API notebookutils fs

Usare le operazioni di montaggio quando si vuole accedere ai dati nell'archiviazione remota tramite un'API del file system locale. È anche possibile accedere ai dati montati usando l'API notebookutils.fs con un percorso montato, ma il formato del percorso è diverso.

Si supponga di aver montato il contenitore Data Lake Storage Gen2 mycontainer in /test usando l'API di montaggio. Quando si accede ai dati con un'API del file system locale, il formato del percorso è simile al seguente:

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

Quando si vuole accedere ai dati usando l'API notebookutils fs , usare getMountPath() per ottenere il percorso accurato:

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

• Elencare le directory.

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

• Leggere il contenuto del file.

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

• Creare una cartella.

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

Accedere ai file nel punto di montaggio tramite il percorso locale

È possibile leggere e scrivere file in un punto di montaggio usando il file system standard. L'esempio python seguente illustra questo modello:

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

Controllare i punti di montaggio esistenti

Usare l'API notebookutils.fs.mounts() per controllare tutte le informazioni sul punto di montaggio esistente:

notebookutils.fs.mounts()

Verificare se esiste un punto di montaggio prima di montare

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

Smontare il punto di montaggio

Usare il codice seguente per smontare il punto di montaggio (/testare in questo esempio):

notebookutils.fs.unmount("/test")

Flusso di lavoro di montaggio-processo-smontaggio

Per una gestione affidabile delle risorse, incapsulare le operazioni di montaggio in un blocco try/finally per assicurarsi che la pulizia venga eseguita anche se si verifica un errore.

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

Limitazioni note

• Le unità di montaggio sono configurazioni a livello di lavoro. Usare l'API mounts per verificare se esiste già un punto di montaggio o se è disponibile.
• Lo smontaggio non avviene automaticamente. Al termine dell'esecuzione dell'applicazione, chiamare un'API di smontaggio nel codice per rilasciare spazio su disco. In caso contrario, il punto di montaggio rimane sul nodo al termine dell'esecuzione dell'applicazione.
• Il montaggio di un account di archiviazione ADLS Gen1 non è supportato.

Contenuti correlati

• NotebookUtils per Fabric
• Utilità del file system NotebookUtils