Utilitários do sistema de ficheiros NotebookUtils para Fabric

notebookutils.fs fornece utilitários para trabalhar com vários sistemas de ficheiros, incluindo Azure Data Lake Storage (ADLS) Gen2 e Azure Blob Storage. Certifique-se de configurar o acesso ao Azure Data Lake Storage Gen2 e ao Armazenamento Blob do Azure adequadamente.

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

notebookutils.fs.help()

A tabela seguinte lista os métodos disponíveis no sistema de ficheiros:

Para operações de montagem e desmontagem, veja Montar e desmontar Ficheiros.

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

• No Lakehouse padrão, os caminhos dos ficheiros são montados no notebook com um tempo de espera de cache de ficheiros de 120 segundos. Isto significa que os ficheiros ficam armazenados em cache na pasta temporária local do caderno durante 120 segundos, mesmo que sejam removidos do Lakehouse. Se quiseres alterar a regra do timeout, podes desmontar os caminhos de ficheiros padrão do Lakehouse e montá-los novamente com um valor diferente fileCacheTimeout .

• Para configurações Lakehouse não padrão, 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 no servidor Lakehouse.

Listar ficheiros

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 comporta-se de forma diferente quando se utiliza um caminho relativo, dependendo do tipo de caderno.

• Num caderno do Spark: O caminho relativo refere-se 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")
  

• Num caderno Python: O caminho relativo é relativo ao diretório de trabalho do sistema de ficheiros local, que por defeito é /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")
  

Ver propriedades do ficheiro

Use notebookutils.fs.ls() para inspecionar propriedades do ficheiro como nome do ficheiro, caminho do ficheiro, tamanho do ficheiro e se um item é um ficheiro 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)

Usa f-strings se quiseres 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 novo diretório

Cria um diretório caso não exista, incluindo quaisquer diretórios pais 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 ficheiro

Copie um ficheiro ou diretório entre sistemas de ficheiros. Definir recurse=True para copiar diretórios recursivamente.

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

O exemplo seguinte mostra uma cópia entre armazenamentos do Lakehouse padrão para uma conta ADLS Gen2.

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

Cópia de ficheiro eficiente

Use fastcp para operações de cópia mais eficientes, especialmente com volumes de dados grandes. O recurse parâmetro é definido para True.

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

Tenha estas considerações em mente:

• notebookutils.fs.fastcp() não suporta copiar ficheiros no OneLake entre regiões. Neste caso, você pode usar notebookutils.fs.cp() em vez disso.
• Devido às limitações do atalho OneLake, quando você precisar notebookutils.fs.fastcp() de copiar dados de atalhos do tipo S3/GCS, recomenda-se usar um caminho montado em vez de um caminho abfss.

Visualizar conteúdo do arquivo

Retorne até aos primeiros max_bytes bytes de um ficheiro como uma string UTF-8.

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

O exemplo seguinte lê os primeiros 1.000 bytes de um ficheiro:

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

Mover o ficheiro

Mover um ficheiro ou diretório entre sistemas de ficheiros.

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

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

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

Gravar arquivo

Escreve uma string UTF-8 num ficheiro.

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 ficheiro

Adicione uma cadeia UTF-8 a um ficheiro.

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 num for ciclo para escrever no mesmo ficheiro, adicione uma sleep instrução de cerca de 0,5 a 1 segundo entre as escritas 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. Definir recurse=True para remover diretórios recursivamente.

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

Verifique se existe um ficheiro ou diretório

Verifique se existe um ficheiro ou diretório no caminho especificado. Devolve True se o caminho existir; caso contrário, devolve 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

Obtém propriedades para um caminho como um mapa de pares nome-valor. Só é suportado para os caminhos do Azure Blob Storage.

Parâmetros:

Retornos: Um dicionário (mapa) contendo propriedades de metadados como tamanho do ficheiro, hora 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 o NotebookUtils