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

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

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

notebookutils.fs.help()

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

Метод	Signature	Описание
`ls`	`ls(path: String): Array`	Показывает содержимое каталога.
`mkdirs`	`mkdirs(path: String): Boolean`	Создает указанный каталог, если он не существует, а также создает необходимые родительские каталоги.
`cp`	`cp(src: String, dest: String, recurse: Boolean = false): Boolean`	Копирует файл или каталог, возможно, между файловыми системами.
`fastcp`	`fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean`	Копирует файл или каталог с помощью azcopy для повышения производительности с большими томами данных.
`mv`	`mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean`	Перемещает файл или каталог, возможно, между файловыми системами.
`put`	`put(file: String, content: String, overwrite: Boolean = false): Boolean`	Записывает заданную строку в файл в кодировке UTF-8.
`head`	`head(file: String, max_bytes: int = 1024 * 100): String`	Возвращает до первых `max_bytes` байтов заданного файла в виде строки, закодированной в UTF-8.
`append`	`append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean`	Добавляет содержимое в файл.
`rm`	`rm(path: String, recurse: Boolean = false): Boolean`	Удаляет файл или каталог.
`exists`	`exists(path: String): Boolean`	Проверяет, существует ли файл или каталог.
`getProperties`	`getProperties(path: String): Map`	Возвращает свойства заданного пути. Доступно только в записных книжках Python (не поддерживается в PySpark, Scala или R).

Замечание

Все методы файловой системы доступны в записных книжках Python, PySpark, Scala и R, если не указано иное. Scala использует имена параметров в стиле camelCase (например, createPath вместо create_path, maxBytes вместо max_bytes).

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

Замечание

При работе с notebookutils.fs учитывайте следующие ограничения и соображения:

Поведение пути зависит от типа записной книжки: в записных книжках Spark относительные пути разрешаются в путь ABFSS, установленный по умолчанию в Lakehouse. В записных книжках Python относительные пути разрешаются в локальный рабочий каталог файловой системы (/home/trusted-service-user/work).
Ограничения параллельной записи: notebookutils.fs.append() и notebookutils.fs.put() не поддерживают одновременную запись в тот же файл из-за отсутствия гарантий атомарности.
Задержка цикла добавления: при использовании notebookutils.fs.append() в циклах добавьте 0,5-1 секунду спящего режима между записью для целостности данных.
Ограничения сочетаний клавиш OneLake: для сочетаний клавиш типа S3/GCS используйте подключенные пути вместо путей ABFS для cp() операций и fastcp() операций.
Ограничения между регионами: fastcp() не поддерживает копирование файлов в OneLake в разных регионах. Вместо этого используйте cp().
Версия среды выполнения: NotebookUtils предназначена для работы с Spark 3.4 (среда выполнения версии 1.2) и выше.
cp() поведение в записных книжках Python: В записных книжках Python cp() внутренне использует тот же механизм на основе azcopy, что и fastcp(), и оба метода ведут себя одинаково.

NotebookUtils работает с файловой системой так же, как и API Spark. Возьмём notebookutils.fs.mkdirs() , к примеру, использование озерных домов:

Использование	Относительный путь от корневого каталога HDFS	Абсолютный путь для файловой системы ABFS	Абсолютный путь к локальной файловой системе на узле драйвера
Не по умолчанию lakehouse	Не поддерживаются	`notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")`	`notebookutils.fs.mkdirs("file:/<new_dir>")`
Озеро по умолчанию	Каталог в разделе "Файлы" или "Таблицы": `notebookutils.fs.mkdirs("Files/<new_dir>")`	`notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")`	`notebookutils.fs.mkdirs("file:/<new_dir>")`

Для стандартного 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)

Замечание

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

Подсказка

Всегда проверяйте возвращаемое значение типа Boolean, чтобы убедиться, что операция выполнена успешно. Используйте notebookutils.fs.exists() для проверки исходного пути перед началом операции копирования.

Следующий пример показывает кросс-хранение копии из стандартного 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)

Подсказка

Используйте fastcp() вместо передачи cp() больших данных. Метод fastcp использует azcopy под капотом, что обеспечивает значительно лучшую пропускную способность для операций с массовыми файлами. В записных книжках Python и cp(), и fastcp() используют один и тот же базовый механизм.

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

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)

Подсказка

Для больших файлов используйте head() с соответствующим значением max_bytes, чтобы избежать проблем с памятью. Значение по умолчанию — 100 КБ (1024 * 100).

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

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

Замечание

Значение max_bytes по умолчанию для разных языков: записные книжки на Python и на Scala используют 102400 (100 КБ), а записные книжки на R используют 65535 (64 КБ). В Scala этот параметр называется maxBytes.

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

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

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

Это важно

Параметр create_path по умолчанию зависит от среды выполнения:

Записные книжки Spark (PySpark, Scala, R): по умолчанию False (false в Scala, FALSE в R). Родительский каталог должен существовать перед операцией перемещения.
Записные книжки Python: по умолчанию True. Родительский каталог создается автоматически, если он не существует.

Чтобы обеспечить согласованное поведение во всех средах выполнения, явно задайте create_path параметр в коде. В Scala этот параметр называется createPath.

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

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() и notebookutils.fs.put() не поддерживают одновременную запись в тот же файл из-за отсутствия гарантий атомарности.

При использовании 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")

Подсказка

Используйте exists() перед выполнением операций с файлами, чтобы предотвратить ошибки. Например, убедитесь, что исходный файл существует, прежде чем пытаться скопировать или переместить его.

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.

Замечание

Этот getProperties метод доступен только в записных книжках Python. Он не поддерживается в записных книжках Spark (PySpark, Scala или R).

Параметры:

Параметр	Тип	Обязательный	Описание
`path`	String	Да	Путь ABFS к файлу или каталогу.

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-05

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы