适用于 Fabric 的 NotebookUtils 文件系统实用工具

notebookutils.fs 提供用于处理各种文件系统的实用工具，包括 Azure Data Lake Storage （ADLS） Gen2 和 Azure Blob 存储。 请确保正确配置对 Azure Data Lake Storage Gen2 和 Azure Blob 存储的访问。

运行以下命令以概要了解可用的方法：

notebookutils.fs.help()

下表列出了可用的文件系统方法：

有关装载和卸载操作，请参阅 文件装载和卸载。

NotebookUtils 以与 Spark API 相同的方式处理文件系统。 以 notebookutils.fs.mkdirs() 和 Lakehouse 的使用 为例：

• 对于默认 Lakehouse，文件路径将装载到笔记本中，默认文件缓存超时为 120 秒。 这意味着文件缓存在笔记本的本地临时文件夹中 120 秒，即使这些文件已从 Lakehouse 中删除也是如此。 如果要更改超时规则，可以卸载默认 Lakehouse 文件路径，并使用其他 fileCacheTimeout 值再次装载它们。

• 对于非默认 Lakehouse 配置，可以在安装 Lakehouse 路径期间设置适当的 fileCacheTimeout 参数。 将超时设置为 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 路径。 例如，notebookutils.fs.ls("Files") 指向默认 Lakehouse 中的 Files 目录。

  例如：

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

• 在 Python 笔记本中：相对路径相对于本地文件系统的工作目录，默认情况下为 /home/trusted-service-user/work. 因此，应使用完整路径而不是相对路径 notebookutils.fs.ls("/lakehouse/default/Files") 来访问默认 Lakehouse 中的 Files 目录。

  例如：

  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-string：

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 路径。

预览文件内容

以 UTF-8 字符串的形式返回文件的第一 max_bytes 个字节。

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

以下示例读取文件的前 1,000 个字节：

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 写入同一个 forsleep 文件时，应在每次重复写入之间添加约 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.")

获取文件属性

获取路径的属性，作为名称值对的映射。 它仅支持 Azure Blob 存储路径。

参数：

返回： 包含元数据属性（例如文件大小、创建时间、上次修改时间和内容类型）的字典（映射）。

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

相关内容

• NotebookUtils 概述
• 使用 NotebookUtils 装载和卸载存储