Montagem e desmontagem de arquivos do NotebookUtils para o Fabric

O NotebookUtils dá suporte a operações de montagem e desmontagem de arquivos por meio do pacote utilitários do Microsoft Spark. Você pode usar as APIs mount, unmount, getMountPath() e mounts() para anexar o armazenamento remoto (ADLS Gen2, Armazenamento de Blobs do Azure, OneLake) a todos os nós de trabalho (nó de driver e nós de trabalhador). Depois que o ponto de montagem do armazenamento estiver configurado, use uma API de arquivo local para acessar dados como se estivessem armazenados no sistema de arquivos local.

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

• Trabalhe com bibliotecas que esperam caminhos de arquivo locais.
• Precisa de semântica consistente do sistema de arquivos no armazenamento em nuvem.
• Acesse os atalhos do OneLake (S3/GCS) com eficiência.
• Crie um código portátil que funcione com vários back-ends de armazenamento.

Referência de API

A tabela a seguir resume as APIs de montagem disponíveis:

Método	Signature	Descrição
mount	mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Monta o armazenamento remoto no ponto de montagem especificado.
unmount	unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Desmonta e remove um ponto de montagem.
mounts	mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]	Lista todos os pontos de montagem existentes com detalhes.
getMountPath	getMountPath(mountPoint: String, scope: String = ""): String	Obtém o caminho do sistema de arquivos local para um ponto de montagem.

Métodos de autenticação

As operações de montagem dão suporte a 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 do Microsoft Entra usa a identidade do executor do notebook, um usuário ou uma entidade de serviço. Ele não requer credenciais explícitas na chamada de montagem, o que a torna a opção mais segura. Use essa opção para montagem do Lakehouse e armazenamento do workspace do Fabric.

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

Dica

Use a autenticação de token do Microsoft Entra sempre que possível. Elimina o risco de exposição de credenciais e não requer nenhuma configuração adicional para o armazenamento do workspace do Fabric.

Chave de conta

Use uma chave de conta quando a conta de armazenamento não der suporte à autenticação do Microsoft Entra ou quando você acessar o armazenamento externo ou de terceiros. Armazene chaves de conta no Azure Key Vault e recupere-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 sas (assinatura de acesso compartilhado)

Use um token SAS (assinatura de acesso compartilhado) para acesso com escopo de permissão limitado por tempo. Essa opção é útil quando você precisa conceder acesso temporário a partes externas. Armazene 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}
)

Importante

Para fins de segurança, evite inserir credenciais diretamente no código. Todos os segredos exibidos nas saídas do notebook são ocultados automaticamente. Para obter mais informações, consulte Redação do segredo.

Montar uma conta do ADLS Gen2

O exemplo a seguir ilustra como montar o Azure Data Lake Storage Gen2. A montagem do Armazenamento de Blobs e do Compartilhamento de Arquivos do Azure funciona da mesma forma.

Este exemplo pressupõe que você tenha uma conta do Data Lake Storage Gen2 chamada storegen2, que tem um contêiner chamado mycontainer que você deseja montar em /test na sessão Spark do notebook.

Para montar o contêiner chamado mycontainer, o NotebookUtils primeiro precisa verificar se você tem permissão para acessar o contêiner. Atualmente, o Fabric dá suporte a três métodos de autenticação para a operação de montagem de trigger: token do Microsoft Entra (padrão), accountKey e sasToken.

Por motivos de segurança, armazene chaves de conta ou tokens SAS no Azure Key Vault (como mostra a captura de tela a seguir). Em seguida, você pode recuperá-los usando a API notebookutils.credentials.getSecret. Para obter mais informações, consulte Sobre as chaves de conta de armazenamento gerenciadas 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

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

• fileCacheTimeout: os blobs são armazenados em cache na pasta temporária local por 120 segundos por padrão. Durante esse tempo, o blobfuse não verifica se o arquivo está atualizado. Você pode definir esse parâmetro para alterar o tempo limite padrão. Quando vários clientes modificam arquivos ao mesmo tempo, para evitar inconsistências entre arquivos locais e remotos, reduza o tempo de cache ou defina-o como 0 para sempre obter os arquivos mais recentes do servidor.
• tempo limite: o tempo limite da operação de montagem é de 30 segundos por padrão. Você pode definir esse parâmetro para alterar o tempo limite padrão. Quando houver muitos executores ou quando o tempo de montagem expirar, aumente o valor.

Você pode usar esses parâmetros como este:

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 tempo limite de cache com base no padrão de acesso:

Scenario	Recomendado fileCacheTimeout	Observações
Operações de leitura intensivas, cliente único	120 (padrão)	Bom equilíbrio de desempenho e frescor.
Acesso moderado a vários clientes	30–60	Reduz o risco de dados obsoletos.
Vários clientes modificando arquivos	0	Sempre busca o mais recente do servidor.
Arquivos raramente mudam	300+	Otimiza o desempenho de leitura.

Padrão de cache zero

Quando vários clientes modificarem arquivos simultaneamente, use uma configuração de cache zero para sempre buscar 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}
)

Observação

Aumente o parâmetro timeout ao montar com muitos executores ou quando ocorrerem erros de tempo limite.

Montar um Lakehouse

A montagem do Lakehouse dá suporte apenas à autenticação de token do 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>"
)

Acessar arquivos no ponto de montagem usando a API notebookutils fs

Use operações de montagem quando quiser acessar dados no armazenamento remoto por meio de uma API do sistema de arquivos local. Você também pode acessar dados montados usando a notebookutils.fs API com um caminho montado, mas o formato de caminho é diferente.

Suponha que você tenha montado o contêiner mycontainer do Data Lake Storage Gen2 em /test usando a API de montagem. Quando você acessa os dados usando a API do sistema de arquivos local, o formato do caminho tem a seguinte aparência:

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

Quando quiser acessar os 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')}")
  

• Ler o conteúdo do arquivo.

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

Acessar arquivos no ponto de montagem por meio do caminho local

Você pode ler e gravar arquivos em um ponto de montagem usando o sistema de arquivos padrão. O exemplo do Python a seguir mostra esse 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"))

Verificar pontos de montagem existentes

Use a notebookutils.fs.mounts() API para verificar todas as informações de ponto de montagem existentes:

notebookutils.fs.mounts()

Dica

Sempre verifique as montagens existentes com mounts() antes de criar novos pontos de montagem para evitar conflitos.

Verificar 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 código a seguir para desmontar o ponto de montagem (/teste neste exemplo):

notebookutils.fs.unmount("/test")

Importante

O mecanismo de desmontagem não é aplicado automaticamente. Quando a execução do aplicativo for concluída, para desmontar o ponto de montagem e liberar o espaço em disco, você precisará chamar explicitamente uma API de desmontagem em seu código. Caso contrário, o ponto de montagem ainda permanece no nó após a conclusão da execução do aplicativo.

Fluxo de trabalho montar-processar-desmontar

Para o gerenciamento de recursos confiável, encapsule operações de montagem em um bloco try/finally para garantir que a limpeza ocorra mesmo se ocorrer 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 de nível de tarefa. 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 do aplicativo for concluída, chame a API de desmontagem em seu código para liberar espaço em disco. Caso contrário, o ponto de montagem permanecerá no nó após a conclusão da execução do aplicativo.
• Não há suporte para a montagem de uma conta de armazenamento do ADLS Gen1.

Conteúdo relacionado

• NotebookUtils for Fabric
• Utilitários do sistema de arquivos NotebookUtils