Служебные программы файловой системы NotebookUtils для Fabric

notebookutils.fs предоставляет служебные программы для работы с различными файловыми системами, включая Azure Data Lake Storage (ADLS) 2-го поколения и хранилище BLOB-объектов Azure. Убедитесь, что доступ к Azure Data Lake Storage 2-го поколения и Хранилищу BLOB-объектов Azure настроен правильно.

Чтобы получить общие сведения о доступных методах, выполните следующие команды:

notebookutils.fs.help()

В следующей таблице перечислены доступные методы файловой системы:

Сведения о операциях подключения и отключения см. в разделе "Подключение файлов" и "Отключение".

NotebookUtils работает с файловой системой так же, как и API Spark. Например, рассмотрим использование notebookutils.fs.mkdirs() и Lakehouse:

• Для Лейкхауса по умолчанию пути к файлам закрепляются в записной книжке, а время ожидания кэша файлов по умолчанию составляет 120 секунд. Это означает, что файлы кэшируются в локальной временной папке записной книжки в течение 120 секунд, даже если они удаляются из Lakehouse. Если вы хотите изменить правило времени ожидания, можно отключить пути к файлам Lakehouse по умолчанию и снова подключить их с другим fileCacheTimeout значением.

• Для конфигураций Lakehouse, отличных от настроек по умолчанию, можно задать подходящий параметр fileCacheTimeout при подключении путей Lakehouse. Установка времени ожидания на 0 гарантирует, что последний файл извлекается из сервера Lakehouse.

Перечень файлов

Чтобы получить список содержимого каталога, используйте notebookutils.fs.ls('Your directory path'). Рассмотрим пример.

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

notebookutils.fs.ls() API ведет себя по-разному при использовании относительного пути в зависимости от типа ноутбука.

• В записной книжке Spark: относительный путь задаётся относительно пути ABFSS по умолчанию в Lakehouse. Например, notebookutils.fs.ls("Files") указывает на каталог Files в Lakehouse по умолчанию.

  Рассмотрим пример.

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

• В записной книжке Python: относительный путь определяется относительно рабочего каталога локальной файловой системы, который по умолчанию является /home/trusted-service-user/work. Вместо относительного пути следует использовать полный путь notebookutils.fs.ls("/lakehouse/default/Files") для доступа к каталогу Files в Lakehouse по умолчанию.

  Рассмотрим пример.

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

Просмотр свойств файла.

Используется notebookutils.fs.ls() для проверки свойств файла, таких как имя файла, путь к файлу, размер файла и наличие элемента в файле или каталоге.

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

Используйте f-strings, если требуется больше доступных для чтения выходных данных:

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

Создать новый каталог

Создайте каталог, если он не существует, включая все необходимые родительские каталоги.

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 

Копирование файла

Копирование файла или каталога в файловой системе. Задайте recurse=True для рекурсивного копирования каталогов.

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

В следующем примере показана копия между разными системами хранения из стандартного Lakehouse в учетную запись ADLS Gen2.

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

Эффективное копирование файла

Используйте fastcp для более эффективных операций копирования, особенно с большими томами данных. Параметр recurse по умолчанию True.

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

Учитывайте следующие аспекты:

• notebookutils.fs.fastcp() не поддерживает копирование файлов в OneLake в разных регионах. В этом случае вместо этого можно использовать notebookutils.fs.cp() .
• Из-за ограничений ярлыка OneLake, если необходимо использовать notebookutils.fs.fastcp() для копирования данных из ярлыка типа S3/GCS, рекомендуется использовать смонтированный путь вместо пути abfss.

Предварительный просмотр содержимого файла

Вернитесь к первым max_bytes байтам файла в виде строки UTF-8.

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

Следующий пример считывает первые 1000 байт файла:

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

Переместить файл

Перемещение файла или каталога между файловыми системами.

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

Используйте именованные параметры, если требуется более четкий код:

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

Запишите файл

Напишите строку UTF-8 в файл.

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

Добавить содержимое в файл

Добавьте строку UTF-8 в файл.

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

При использовании notebookutils.fs.append API в цикле для записи в тот же for файл добавьте оператор sleep с задержкой около 0,5–1 секунды между повторяющимися записями. Эта рекомендация обусловлена тем, что внутренняя операция notebookutils.fs.append API flush асинхронна, поэтому короткая задержка помогает обеспечить целостность данных.

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

Удалить файл или каталог

Удаление файла или каталога. Установите recurse=True, чтобы рекурсивно удалять каталоги.

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

Проверка наличия файла или каталога

Проверьте, существует ли файл или каталог по указанному пути. Возвращается True , если путь существует; в противном случае возвращается 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.")

Получение свойств файла

Получите свойства пути в формате отображения пар "имя-значение". Он поддерживается только для путей к хранилищу BLOB-объектов Azure.

Параметры:

Возвращает: Словарь (карта), содержащий свойства метаданных, такие как размер файла, время создания, время последнего изменения и тип содержимого.

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

Связанный контент

• Обзор NotebookUtils
• Подключение и отключение хранилища с помощью NotebookUtils