用途
Azure Data Lake Storage Gen2 SDK for Python 面向大数据分析工作负载，提供分层文件系统能力，用于在 Azure Data Lake Storage Gen2 上执行文件与目录操作。
安装与环境变量
安装命令：
pip install azure-storage-file-datalake azure-identity
环境变量：
AZURE_STORAGE_ACCOUNT_URL=https://<account>.dfs.core.windows.net
身份验证
使用 DefaultAzureCredential 与 DataLakeServiceClient 建立服务客户端：
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：文件操作
主要能力
文件系统操作
可创建文件系统（容器）、获取已有文件系统、删除文件系统以及列举文件系统：
file_system_client = service_client.create_file_system("myfilesystem")
file_system_client = service_client.get_file_system_client("myfilesystem")
service_client.delete_file_system("myfilesystem")
for fs in service_client.list_file_systems():
print(fs.name)
目录操作
支持创建目录、创建嵌套目录、获取目录客户端、删除目录以及重命名/移动目录：
directory_client = file_system_client.create_directory("mydir")
directory_client = file_system_client.create_directory("path/to/nested/dir")
directory_client = file_system_client.get_directory_client("mydir")
directory_client.delete_directory()
directory_client.rename_directory(new_name="myfilesystem/newname")
文件操作
上传文件支持从本地文件、字节数据上传，以及针对大文件使用 append_data 与 flush_data 分块追加并提交：
file_client = file_system_client.get_file_client("path/to/file.txt")
with open("local-file.txt", "rb") as data:
file_client.upload_data(data, overwrite=True)
file_client.upload_data(b"Hello, Data Lake!", overwrite=True)
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)
下载文件支持读取全部内容、写入本地文件以及按范围下载：
download = file_client.download_file()
content = download.readall()
with open("downloaded.txt", "wb") as f:
download = file_client.download_file()
download.readinto(f)
download = file_client.download_file(offset=0, length=100)
删除文件：
file_client.delete_file()
列举内容
可列举路径（文件与目录）、列举指定目录下的路径以及递归列举：
for path in file_system_client.get_paths():
print(f"{'DIR' if path.is_directory else 'FILE'}: {path.name}")
for path in file_system_client.get_paths(path="mydir"):
print(path.name)
for path in file_system_client.get_paths(path="mydir", recursive=True):
print(path.name)
文件/目录属性
可获取属性（如大小、最后修改时间）并设置元数据：
properties = file_client.get_file_properties()
print(f"Size: {properties.size}")
print(f"Last modified: {properties.last_modified}")
file_client.set_metadata(metadata={"processed": "true"})
访问控制（ACL）
可获取 ACL、设置 ACL 以及递归更新 ACL 条目：
acl = directory_client.get_access_control()
print(f"Owner: {acl['owner']}")
print(f"Permissions: {acl['permissions']}")
directory_client.set_access_control(owner="user-id", permissions="rwxr-x---")
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=True)
download = await file_client.download_file()
content = await download.readall()
import asyncio
asyncio.run(datalake_operations())
最佳实践
- 使用分层命名空间以获得文件系统语义
- 大文件上传使用 append_data + flush_data
- 在目录级别设置 ACL 并继承给子项
- 高吞吐场景使用异步客户端
- 使用 get_paths 并设置 recursive=True 进行完整目录列举
- 为自定义文件属性设置元数据
- 简单对象存储用例可考虑 Blob API
适用场景
该技能适用于执行上述概述中描述的工作流或操作。
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。