你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure DataLake 服务客户端库 - 版本 12.14.0

项目
11/09/2023

概述

此 Python 预览包包括存储 SDK 中提供的 ADLS Gen2 特定 API 支持。这包括：

(HNS) 存储帐户启用分层命名空间 (创建、重命名、删除) 的新目录级别操作。对于已启用 HNS 的帐户，重命名/移动操作是原子操作。
(HNS) 帐户启用分层命名空间 (获取/设置 ACL) 权限相关操作。

入门

先决条件

使用此包需要 Python 3.7 或更高版本。有关更多详细信息，请阅读有关 Azure SDK for Python 版本支持策略的页面。
必须具有 Azure 订阅和 Azure 存储帐户才能使用此包。

安装包

使用 pip 安装适用于 Python 的 Azure DataLake 存储客户端库：

pip install azure-storage-file-datalake --pre

创建存储帐户

如果要创建新的存储帐户，可以使用 Azure 门户、Azure PowerShell或 Azure CLI：

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

验证客户端

与 DataLake Storage 的交互从 DataLakeServiceClient 类的实例开始。需要现有的存储帐户、其 URL 和凭据来实例化客户端对象。

获取凭据

若要对客户端进行身份验证，有以下几种选项：

使用 SAS 令牌字符串
使用帐户共享访问密钥
使用 azure.identity 中的令牌凭据

或者，可以使用方法通过存储连接字符串from_connection_string进行身份验证。请参阅示例：使用连接字符串创建客户端。

如果帐户 URL 已有 SAS 令牌，则可以省略凭据。

创建客户端

准备好帐户 URL 和凭据后，可以创建 DataLakeServiceClient：

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient(account_url="https://<my-storage-account-name>.dfs.core.windows.net/", credential=credential)

关键概念

DataLake 存储提供四种类型的资源：

存储帐户
存储帐户中的文件系统
文件系统下的目录
文件系统或目录下的文件

异步客户端

此库包含 Python 3.5+ 上支持的完整异步 API。若要使用它，必须先安装异步传输，例如 aiohttp。有关详细信息，请参阅 azure-core 文档。

不再需要异步客户端和凭据时，应将其关闭。这些对象是异步上下文管理器并定义异步 close 方法。

客户端

DataLake 存储 SDK 提供四个不同的客户端来与 DataLake 服务交互：

DataLakeServiceClient - 此客户端在帐户级别与 DataLake 服务交互。它提供检索和配置帐户属性以及列出、创建和删除帐户中的文件系统的操作。对于与特定文件系统、目录或文件相关的操作，也可以使用或 get_directory_clientget_file_system_client 函数检索这些实体的get_file_client客户端。
FileSystemClient - 此客户端表示与特定文件系统的交互，即使该文件系统尚不存在。它提供创建、删除或配置文件系统的操作，包括列出文件系统下的路径、上传和删除文件系统中的文件或目录的操作。对于与特定文件相关的操作，也可以使用函数检索 get_file_client 客户端。对于与特定目录相关的操作，可以使用函数检索 get_directory_client 客户端。
DataLakeDirectoryClient - 此客户端表示与特定目录的交互，即使该目录尚不存在。它提供目录操作创建、删除、重命名、获取属性和设置属性操作。
DataLakeFileClient - 此客户端表示与特定文件的交互，即使该文件尚不存在也是如此。它提供用于追加数据、刷新数据、删除、创建和读取文件的文件操作。
DataLakeLeaseClient - 此客户端表示与 FileSystemClient、DataLakeDirectoryClient 或 DataLakeFileClient 的租用交互。它提供获取、续订、释放、更改和中断资源租约的操作。

示例

以下部分提供了几个代码片段，涵盖了一些最常见的 Storage DataLake 任务，包括：

使用连接字符串创建客户端
上传文件
下载文件
枚举路径

使用连接字符串创建客户端

使用 Azure 存储帐户连接字符串创建 DataLakeServiceClient。

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

上传文件

将文件上传到文件系统。

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

下载文件

从文件系统下载文件。

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

枚举路径

列出文件系统中的路径。

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

可选配置

可选关键字 (keyword) 可在客户端和每个操作级别传入的参数。

重试策略配置

在实例化客户端时使用以下关键字 (keyword) 参数来配置重试策略：

retry_total (int) ：允许的重试总数。优先于其他计数。 retry_total=0如果不想对请求重试，请传入。默认值为 10。
retry_connect (int) ：重试多少个与连接相关的错误。默认值为 3。
retry_read (int) ：读取错误时重试的次数。默认值为 3。
retry_status (int) ：对错误状态代码重试的次数。默认值为 3。
retry_to_secondary (bool) ：是否应将请求重试到辅助数据库（如果可以）。应仅启用 RA-GRS 帐户，并可以处理可能过时的数据。默认为 False。

其他客户端/每操作配置

其他可选配置关键字 (keyword) 可在客户端或每个操作上指定的参数。

客户端关键字 (keyword) 参数：

connection_timeout (int) ：客户端将等待与服务器建立连接的秒数。默认为 20 秒。
read_timeout (int) ：客户端在连续读取操作之间等待服务器响应的秒数。这是套接字级别超时，不受整体数据大小的影响。客户端读取超时将自动重试。默认值为 60 秒。
传输 (任何) ：用户提供的用于发送 HTTP 请求的传输。

按操作关键字 (keyword) 参数：

raw_response_hook (可调用) ：给定回调使用从服务返回的响应。
raw_request_hook (可调用) ：给定的回调在发送到服务之前使用请求。
client_request_id (str) ：请求的可选用户指定标识。
user_agent (str) ：将自定义值追加到要随请求一起发送的用户代理标头。
logging_enable (bool) ：在 DEBUG 级别启用日志记录。默认为 False。也可以在客户端级别传入，以为所有请求启用它。
logging_body (bool) ：启用记录请求和响应正文。默认为 False。也可以在客户端级别传入，以为所有请求启用它。
标头 (dict) ：将自定义标头作为键值对传入。例如 headers={'CustomValue': value}

疑难解答

常规

DataLake 存储客户端会引发 Azure Core 中定义的异常。

此列表可用于引用以捕获引发的异常。若要获取异常的特定错误代码，请使用 error_code 属性，即 exception.error_code。

日志记录

此库使用标准日志记录库进行日志记录。有关 HTTP 会话 (URL、标头等的基本信息，) 在 INFO 级别记录。

可以使用参数在客户端 logging_enable 上启用详细的调试级别日志记录，包括请求/响应正文和未处理标头：

import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = DataLakeServiceClient.from_connection_string("your_connection_string", logging_enable=True)

同样，即使没有为客户端启用详细日志记录，logging_enable 也可以为单个操作启用：

service_client.list_file_systems(logging_enable=True)

后续步骤

其他文档

ADLS Gen1 到 ADLS Gen2 API 映射表有关Data Lake Storage Gen2的更多 REST 文档，请参阅有关 docs.microsoft.com 的Data Lake Storage Gen2文档。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。