Utilidades del sistema de archivos NotebookUtils para Fabric

notebookutils.fs proporciona utilidades para trabajar con varios sistemas de archivos, como Azure Data Lake Storage (ADLS) Gen2 y Azure Blob Storage. Asegúrese de configurar el acceso a Azure Data Lake Storage Gen2 y Azure Blob Storage adecuadamente.

Ejecute los siguientes comandos para obtener información general sobre los métodos disponibles:

notebookutils.fs.help()

En la tabla siguiente se enumeran los métodos disponibles del sistema de archivos:

Para las operaciones de montaje y desmontaje, consulte Montaje y desmontaje de archivos.

NotebookUtils funciona con el sistema de archivos de la misma manera que las API de Spark. Tome como ejemplo el uso de notebookutils.fs.mkdirs() y de Lakehouse:

• Para el Lakehouse por defecto, las rutas de acceso de archivos se montan en el notebook con un tiempo de espera predeterminado de la caché de archivos de 120 segundos. Esto significa que los archivos se almacenan en caché en la carpeta temporal local del cuaderno durante 120 segundos, incluso si se quitan de Lakehouse. Si desea cambiar la regla de tiempo de espera, puede desmontar las rutas de acceso de archivo predeterminadas de Lakehouse y montarlas de nuevo con un valor diferente fileCacheTimeout.

• Para configuraciones no predeterminadas de Lakehouse, puede establecer el parámetro adecuado fileCacheTimeout durante el monte de las rutas de acceso a Lakehouse. Si se establece el tiempo de espera en 0, se garantiza que el archivo más reciente se recupera desde el servidor Lakehouse.

Enumerar archivos

Para enumerar el contenido de un directorio, use notebookutils.fs.ls('Your directory path'). Por ejemplo:

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

La notebookutils.fs.ls() API se comporta de forma diferente cuando se usa una ruta de acceso relativa, según el tipo de cuaderno.

• En un cuaderno de Spark: la ruta de acceso relativa es relativa a la ruta de acceso ABFSS predeterminada del almacén de lago de datos. Por ejemplo, notebookutils.fs.ls("Files") apunta al directorio Files en el almacén de lago de datos predeterminado.

  Por ejemplo:

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

• En un cuaderno de Python: la ruta de acceso relativa es relativa al directorio de trabajo del sistema de archivos local, que de forma predeterminada es /home/trusted-service-user/work. Por lo tanto, debe usar la ruta de acceso completa en lugar de la ruta de acceso relativa notebookutils.fs.ls("/lakehouse/default/Files") para acceder al directorio de Files en el almacén de lago de datos predeterminado.

  Por ejemplo:

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

Vea las propiedades del archivo.

Use notebookutils.fs.ls() para inspeccionar propiedades de archivo como el nombre de archivo, la ruta de acceso de archivo, el tamaño del archivo y si un elemento es un archivo o directorio.

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

Use f-strings si desea obtener una salida más legible:

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

Creación de un directorio

Cree un directorio si no existe, incluidos los directorios primarios necesarios.

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 archivo

Copie un archivo o directorio entre sistemas de archivos. Configura recurse=True para copiar los directorios de forma recursiva.

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

En el siguiente ejemplo se muestra una copia de almacenamiento cruzado del Lakehouse predeterminado a una cuenta de ADLS Gen2.

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

Copiar archivo con rendimiento óptimo

Se usa fastcp para operaciones de copia más eficaces, especialmente con grandes volúmenes de datos. El recurse parámetro tiene Truecomo valor predeterminado .

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

Tenga en cuenta las consideraciones siguientes:

• notebookutils.fs.fastcp() no admite la copia de archivos en OneLake entre regiones. En este caso, puede usar notebookutils.fs.cp() en su lugar.
• Debido a las limitaciones del acceso directo de OneLake, cuando necesite usar notebookutils.fs.fastcp() para copiar datos desde el acceso directo de tipo S3/GCS, se recomienda usar una ruta de acceso montada en lugar de una ruta de acceso abfss.

Vista previa del contenido del archivo

Devuelve hasta los primeros max_bytes bytes de un archivo como una cadena UTF-8.

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

En el ejemplo siguiente se leen los primeros 1000 bytes de un archivo:

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

Mover archivo

Mueva un archivo o un directorio entre sistemas de archivos.

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

Use parámetros con nombre si desea código más claro:

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

Escribir archivo

Escriba una cadena UTF-8 en un archivo.

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

Adición de contenido a un archivo

Anexe una cadena UTF-8 a un archivo.

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

Al usar la notebookutils.fs.append API en un for bucle para escribir en el mismo archivo, agregue una sleep sentencia de aproximadamente 0,5 a 1 segundo entre las escrituras periódicas. Esta recomendación se debe a que la operación interna notebookutils.fs.append de la API flush es asincrónica, por lo que un breve retraso ayuda a asegurar la integridad de los datos.

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

Eliminación de un archivo o directorio

Quite un archivo o directorio. Configurar recurse=True para quitar directorios de forma recursiva.

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

Comprobar si existe un archivo o directorio

Compruebe si existe un archivo o directorio en la ruta de acceso especificada. Devuelve True si existe la ruta de acceso; de lo contrario, devuelve 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.")

Obtener las propiedades de archivos

Obtiene las propiedades de una ruta de acceso como un mapa de pares nombre-valor. Solo es compatible con las rutas de acceso de Azure Blob Storage.

Parámetros:

Devuelve: Diccionario (mapa) que contiene propiedades de metadatos como el tamaño del archivo, la hora de creación, la hora de última modificación y el tipo de contenido.

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

Contenido relacionado

• Introducción a NotebookUtils
• Montaje y desmontaje del almacenamiento con NotebookUtils