azure-storage-file-datalake-py

Azure Data Lake Storage Gen2 SDK for Python

用于大数据分析工作负载的分层文件系统。

安装

pip install azure-storage-file-datalake azure-identity

环境变量

AZURE_STORAGE_ACCOUNT_URL=https://<account>.dfs.core.windows.net

身份验证

from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient

credential = DefaultAzureCredential()
account_url = "https://<account>.dfs.core.windows.net"

service_client = DataLakeServiceClient(account_url=account_url, credential=credential)

客户端层级

客户端	用途
DataLakeServiceClient	帐户级操作
FileSystemClient	容器（文件系统）操作
DataLakeDirectoryClient	目录操作
DataLakeFileClient	文件操作

这些是彼此独立的代码片段，并非可一次性运行的脚本。执行写入、重命名、递归 ACL 更改或删除之前，请确认帐户、文件系统和路径，并保护现有数据。切勿将生产环境占位值用作清理目标。请限制递归列表的范围和下载字节数，并使用不会覆盖现有文件的本地输出路径。递归 ACL 更新可能会部分失败：请检查计数器和失败详情，并且仅在范围精确的情况下恢复操作。在失败路径中，也要关闭异步凭据和客户端；上传成功并不能证明业务结果正确。

文件系统操作

# Create file system (container)
file_system_client = service_client.create_file_system("myfilesystem")

# Get existing
file_system_client = service_client.get_file_system_client("myfilesystem")

# Delete
service_client.delete_file_system("myfilesystem")

# List file systems
for fs in service_client.list_file_systems():
    print(fs.name)

目录操作

file_system_client = service_client.get_file_system_client("myfilesystem")

# Create directory
directory_client = file_system_client.create_directory("mydir")

# Create nested directories
directory_client = file_system_client.create_directory("path/to/nested/dir")

# Get directory client
directory_client = file_system_client.get_directory_client("mydir")

# Delete directory
directory_client.delete_directory()

# Rename/move directory
directory_client.rename_directory(new_name="myfilesystem/newname")

文件操作

上传文件

# Get file client
file_client = file_system_client.get_file_client("path/to/file.txt")

# Upload from local file
with open("local-file.txt", "rb") as data:
    file_client.upload_data(data, overwrite=False)

# Upload bytes
file_client.upload_data(b"Hello, Data Lake!", overwrite=False)

# Separate append example: create an explicitly new empty file first.
file_client = file_system_client.create_file("disposable-append-example.txt")
file_client.append_data(data=b"chunk1", offset=0, length=6)
file_client.append_data(data=b"chunk2", offset=6, length=6)
file_client.flush_data(12)  # Commit the data

下载文件

file_client = file_system_client.get_file_client("path/to/file.txt")

# Download all content
download = file_client.download_file()
content = download.readall()

# Download to file
with open("downloaded.txt", "wb") as f:
    download = file_client.download_file()
    download.readinto(f)

# Download range
download = file_client.download_file(offset=0, length=100)

删除文件

file_client.delete_file()

列出内容

# List paths (files and directories)
for path in file_system_client.get_paths():
    print(f"{'DIR' if path.is_directory else 'FILE'}: {path.name}")

# List paths in directory
for path in file_system_client.get_paths(path="mydir"):
    print(path.name)

# Recursive listing
for path in file_system_client.get_paths(path="mydir", recursive=True):
    print(path.name)

文件/目录属性

# Get properties
properties = file_client.get_file_properties()
print(f"Size: {properties.size}")
print(f"Last modified: {properties.last_modified}")

# Set metadata
file_client.set_metadata(metadata={"processed": "true"})

访问控制（ACL）

# Get ACL
acl = directory_client.get_access_control()
print(f"Owner: {acl['owner']}")
print(f"Permissions: {acl['permissions']}")

# Set ACL
directory_client.set_access_control(
    owner="user-id",
    permissions="rwxr-x---"
)

# Update ACL entries
from azure.storage.filedatalake import AccessControlChangeResult
directory_client.update_access_control_recursive(
    acl="user:user-id:rwx"
)

异步客户端

from azure.storage.filedatalake.aio import DataLakeServiceClient
from azure.identity.aio import DefaultAzureCredential

async def datalake_operations():
    credential = DefaultAzureCredential()
    
    async with DataLakeServiceClient(
        account_url="https://<account>.dfs.core.windows.net",
        credential=credential
    ) as service_client:
        file_system_client = service_client.get_file_system_client("myfilesystem")
        file_client = file_system_client.get_file_client("test.txt")
        
        await file_client.upload_data(b"async content", overwrite=False)
        
        download = await file_client.download_file()
        content = await download.readall()

import asyncio
asyncio.run(datalake_operations())

最佳实践

1. 使用分层命名空间以支持文件系统语义
2. 使用 append_data + flush_data 上传大文件
3. 检查 ACL 范围：默认 ACL 会影响新建的后代对象；现有后代对象需要通过单独授权的递归操作进行更改
4. 在高吞吐量场景中使用异步客户端
5. 使用带有 recursive=True 的 get_paths 列出完整目录
6. 设置元数据以添加自定义文件属性
7. 对于简单的对象存储用例，可考虑使用 Blob API

适用场景

当需要执行概述中所述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。