Utilitários do sistema de arquivos NotebookUtils para Fabric

notebookutils.fs fornece utilitários para trabalhar com vários sistemas de arquivos, incluindo o Azure Data Lake Storage (ADLS) Gen2 e o Armazenamento de Blobs do Azure. Configure o acesso ao Azure Data Lake Storage Gen2 e ao Armazenamento de Blobs do Azure adequadamente.

Execute os seguintes comandos para obter uma visão geral dos métodos disponíveis:

notebookutils.fs.help()

A tabela a seguir lista os métodos disponíveis do sistema de arquivos:

Para operações de montagem e desmontagem, consulte Montagem e desmontagem de arquivos.

O NotebookUtils funciona com o sistema de arquivos da mesma forma que as APIs do Spark. Tome notebookutils.fs.mkdirs() e o uso do Lakehouse como exemplo:

• Para o Lakehouse padrão, os caminhos de arquivo são montados em seu notebook com um tempo limite de cache de arquivo padrão de 120 segundos. Isso significa que os arquivos são armazenados em cache na pasta temporária local do notebook por 120 segundos, mesmo que sejam removidos do Lakehouse. Se você quiser alterar a regra de tempo limite, poderá desmontar os caminhos de arquivo padrão do Lakehouse e montá-los novamente com um valor diferente fileCacheTimeout .

• Para configurações não padrão do Lakehouse, você pode definir o parâmetro apropriado fileCacheTimeout durante a montagem dos caminhos lakehouse. Definir o tempo limite como 0 garante que o arquivo mais recente seja buscado do servidor Lakehouse.

Listar arquivos

Para listar o conteúdo de um diretório, use notebookutils.fs.ls('Your directory path'). Por exemplo:

notebookutils.fs.ls("Files/tmp") # Relative path works with different base paths depending on notebook type
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # Absolute path using ABFS file system
notebookutils.fs.ls("file:/tmp")  # Full path of the local file system of driver node

A notebookutils.fs.ls() API se comporta de forma diferente ao usar um caminho relativo, dependendo do tipo de notebook.

• Em um notebook do Spark: o caminho relativo se refere ao caminho ABFSS padrão do Lakehouse. Por exemplo, notebookutils.fs.ls("Files") aponta para o diretório Files no Lakehouse padrão.

  Por exemplo:

  notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
  

• Em um notebook python: o caminho relativo é relativo ao diretório de trabalho do sistema de arquivos local, que por padrão é /home/trusted-service-user/work. Portanto, você deve usar o caminho completo em vez de um caminho relativo notebookutils.fs.ls("/lakehouse/default/Files") para acessar o diretório Files no Lakehouse padrão.

  Por exemplo:

  notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
  

Exibir propriedades de arquivo

Use notebookutils.fs.ls() para inspecionar as propriedades do arquivo, como nome do arquivo, caminho do arquivo, tamanho do arquivo e se um item é um arquivo ou diretório.

files = notebookutils.fs.ls('Your directory path')
for file in files:
    print(file.name, file.isDir, file.isFile, file.path, file.size)

Use cadeias de caracteres f se desejar uma saída mais legível:

files = notebookutils.fs.ls("Files/data")
for file in files:
    print(f"Name: {file.name}, Size: {file.size}, IsDir: {file.isDir}, Path: {file.path}")

Criar um diretório

Crie um diretório se ele não existir, incluindo todos os diretórios predecessores necessários.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # Works with the default Lakehouse files using relative path 
notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # Based on ABFS file system 
notebookutils.fs.mkdirs("file:/<new_dir>")  # Based on local file system of driver node 

Copiar arquivo

Copie um arquivo ou diretório entre sistemas de arquivos. Defina recurse=True para copiar diretórios recursivamente.

notebookutils.fs.cp('source file or directory', 'destination file or directory', recurse=True)

O exemplo a seguir mostra uma cópia de armazenamento cruzado do Lakehouse padrão para uma conta do ADLS Gen2:

notebookutils.fs.cp(
    "Files/local_data",
    "abfss://<container>@<account>.dfs.core.windows.net/remote_data",
    recurse=True
)

Arquivo de cópia com desempenho

Use fastcp para operações de cópia mais eficientes, especialmente com grandes volumes de dados. O recurse parâmetro usa Truecomo padrão .

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', recurse=True)

Lembre-se do seguinte:

• notebookutils.fs.fastcp() não dá suporte à cópia de arquivos no OneLake entre regiões. Nesse caso, você pode usar notebookutils.fs.cp().
• Devido às limitações do atalho do OneLake, quando você precisa usar notebookutils.fs.fastcp() para copiar dados do atalho de tipo S3/GCS, é recomendável usar um caminho montado em vez de um caminho abfss.

Visualizar o conteúdo do arquivo

Retorne até os primeiros max_bytes bytes de um arquivo como uma cadeia de caracteres UTF-8.

notebookutils.fs.head('file path', max_bytes)

O exemplo a seguir lê os primeiros 1.000 bytes de um arquivo:

content = notebookutils.fs.head("Files/data/sample.txt", 1000)
print(content)

Mover arquivo

Mova um arquivo ou diretório entre sistemas de arquivos.

notebookutils.fs.mv('source file or directory', 'destination directory', create_path=True, overwrite=True)

Use parâmetros nomeados se desejar um código mais claro:

notebookutils.fs.mv("Files/source.csv", "Files/new_folder/dest.csv", create_path=True, overwrite=True)

Gravar arquivo

Escreva uma cadeia de caracteres UTF-8 em um arquivo.

notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it already exists

Acrescentar conteúdo a um arquivo

Acrescente uma cadeia de caracteres UTF-8 a um arquivo.

notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it doesn't exist

Ao usar a notebookutils.fs.append API em um for loop para gravar no mesmo arquivo, adicione uma sleep instrução de cerca de 0,5 a 1 segundo entre as gravações recorrentes. Essa recomendação ocorre porque a operação de notebookutils.fs.append interna da API flush é assíncrona, portanto, um pequeno atraso ajuda a garantir a integridade dos dados.

import time

for i in range(100):
    notebookutils.fs.append("Files/output/data.txt", f"Line {i}\n", True)
    time.sleep(0.5)  # Prevent data integrity issues

Excluir arquivo ou diretório

Remova um arquivo ou diretório. Defina recurse=True para remover diretórios recursivamente.

notebookutils.fs.rm('file path', recurse=True) 

Verificar se existe um arquivo ou diretório

Verifique se existe um arquivo ou diretório no caminho especificado. Ele retornará True se o caminho existir; caso contrário, retornará False.

notebookutils.fs.exists("Files/data/input.csv")

if notebookutils.fs.exists("Files/data/input.csv"):
    notebookutils.fs.cp("Files/data/input.csv", "Files/backup/input.csv")
    print("File copied successfully.")
else:
    print("Source file not found.")

Obter propriedades do arquivo

Obtenha as propriedades de um caminho no formato de um mapa de pares nome-valor. É compatível apenas com caminhos do Azure Blob Storage.

Parâmetros:

Retorna: Um dicionário (mapa) que contém propriedades de metadados, como tamanho do arquivo, tempo de criação, hora da última modificação e tipo de conteúdo.

properties = notebookutils.fs.getProperties("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")
print(properties)

Conteúdo relacionado

• Visão geral do NotebookUtils
• Montar e desmontar o armazenamento com NotebookUtils