Montagem e desmontagem de ficheiros do NotebookUtils para o Fabric

O NotebookUtils suporta operações de montagem e desmontagem de ficheiros através do pacote Microsoft Spark Utilities. Pode usar as APIs mount, unmount, getMountPath() e mounts() para ligar armazenamento remoto (ADLS Gen2, Azure Blob Storage, OneLake) a todos os nós em funcionamento (nó driver e nós de trabalho). Depois que o ponto de montagem de armazenamento estiver instalado, use a API de arquivo local para acessar os dados como se estivessem armazenados no sistema de arquivos local.

As operações de montagem são particularmente úteis quando:

• Trabalhe com bibliotecas que esperem caminhos de ficheiros locais.
• É necessário uma semântica consistente do sistema de ficheiros em todo o armazenamento na cloud.
• Aceda eficientemente aos atalhos do OneLake (S3/GCS).
• Cria código portátil que funcione com múltiplos backends de armazenamento.

Referência da API

A tabela seguinte resume as APIs de montagem disponíveis:

Métodos de autenticação

As operações de montagem suportam vários métodos de autenticação. Escolha o método com base no tipo de armazenamento e nos requisitos de segurança.

Token do Microsoft Entra (padrão e recomendado)

A autenticação de token Microsoft Entra utiliza a identidade do executor do portátil, seja um utilizador ou um principal de serviço. Não requer credenciais explícitas na chamada mount, o que o torna a opção mais segura. Use esta opção para montagem do Lakehouse e armazenamento do espaço de trabalho do Fabric.

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

Chave da conta

Use uma chave de acesso quando a conta de armazenamento não suportar autenticação Microsoft Entra, ou quando aceder a armazenamento externo ou de terceiros. Guarda as chaves da conta no Azure Key Vault e recupera-as com a 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 assinatura de acesso partilhado (SAS)

Use um token de assinatura de acesso partilhado (SAS) para acesso com tempo limitado e com âmbito de permissões. Esta opção é útil quando precisa de conceder acesso temporário a terceiros. Armazenar tokens SAS no 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}
)

Crie uma conta ADLS Gen2

O exemplo a seguir ilustra como montar o Azure Data Lake Storage Gen2. Montar Blob Storage e Azure File Share funciona de forma semelhante.

Este exemplo considera-se que tens uma conta do Data Lake Storage Gen2 chamada storegen2, que tem um contentor chamado mycontainer que desejas montar em /test na sessão Spark do notebook.

Para montar o contentor chamado mycontainer, o NotebookUtils precisa primeiro de verificar se tem permissão para aceder ao contentor. Atualmente, o Fabric suporta três métodos de autenticação para a operação de montagem do gatilho: token Microsoft Entra (por defeito), accountKey e sasToken.

Por razões de segurança, armazene chaves de conta ou tokens SAS no Azure Key Vault (como mostra a captura de ecrã seguinte). Em seguida, você pode recuperá-los usando a notebookutils.credentials.getSecret API. Para obter mais informações sobre o Azure Key Vault, consulte Sobre as chaves de conta de armazenamento gerenciado do Azure Key Vault.

Código de exemplo para o 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 exemplo 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 montagem

Pode ajustar o comportamento de montagem no mapa extraConfigs com os seguintes parâmetros opcionais:

• fileCacheTimeout: Os blobs são armazenados em cache na pasta temporária local durante 120 segundos por defeito. Durante este tempo, o blobfuse não verifica se o ficheiro está atualizado. Podes definir este parâmetro para alterar o tempo de timeout padrão. Quando vários clientes modificam ficheiros ao mesmo tempo, para evitar inconsistências entre ficheiros locais e remotos, reduz o tempo de cache ou define-o para 0 para obter sempre os ficheiros mais recentes do servidor.
• Tempo morto: O tempo limite da operação de montagem é de 30 segundos por defeito. Podes definir este parâmetro para alterar o tempo de timeout padrão. Quando existirem muitos executores ou quando o tempo limite de montagem expirar, aumente o valor.

Você pode usar estes parâmetros assim:

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

Recomendações de configuração de cache

Escolha um valor de timeout da cache com base no seu padrão de acesso:

Padrão zero-cache

Quando vários clientes modificam ficheiros simultaneamente, use uma configuração de cache zero para sempre obter a versão mais recente do 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 um Lakehouse

A montagem Lakehouse suporta apenas autenticação de token Microsoft Entra. Código de exemplo para montar um Lakehouse em /<mount_name>:

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

Aceda aos ficheiros sob o ponto de montagem utilizando a API fs notebookutils

Use operações de montagem quando quiser aceder a dados em armazenamento remoto através de uma API de sistema de ficheiros local. Também pode aceder a dados montados usando a notebookutils.fs API com um caminho montado, mas o formato do caminho é diferente.

Suponha que você montou o contêiner do Data Lake Storage Gen2 mycontainer em /test usando a API de montagem. Quando você acessa os dados com uma API de sistema de arquivos local, o formato de caminho é assim:

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

Quando quiser aceder aos dados usando a notebookutils fs API, use getMountPath() para obter o caminho preciso:

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

• Listar diretórios.

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

• Leia o conteúdo do ficheiro.

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

• Crie um diretório.

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

Aceda aos ficheiros no ponto de montagem através do caminho local

Pode ler e escrever ficheiros num ponto de montagem usando o sistema de ficheiros padrão. O seguinte exemplo em Python mostra este padrão:

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

Verifique os pontos de montagem existentes

Use a notebookutils.fs.mounts() API para verificar toda a informação existente sobre pontos de montagem:

notebookutils.fs.mounts()

Verifique se existe uma montagem antes de montar

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

Desmonte o ponto de montagem

Use o seguinte código para desmontar o seu ponto de montagem (/teste neste exemplo):

notebookutils.fs.unmount("/test")

Fluxo de trabalho montar-processar-desmontar

Para uma gestão fiável de recursos, envolver as operações de montagem em um try/finally bloco para garantir que a limpeza ocorre mesmo que ocorra um erro.

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

Limitações conhecidas

• As montagens são configurações ao nível do trabalho. Use a mounts API para verificar se um ponto de montagem já existe ou está disponível.
• A desmontagem não acontece automaticamente. Quando a execução da aplicação terminar, chame uma API de desmontar no seu código para libertar espaço em disco. Caso contrário, o ponto de montagem permanece no nó após o término da execução da aplicação.
• Não há suporte para a montagem de uma conta de armazenamento ADLS Gen1.

Conteúdo relacionado

• NotebookUtils para Fabric
• Utilitários do sistema de ficheiros NotebookUtils