Azure DataLake服务Python客户端库

概述

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

1. 针对启用分层命名空间（HNS）的存储帐户的新目录级别操作（创建、重命名、删除）。对于启用HNS的帐户，重命名/移动操作是原子的。
2. 与权限相关的操作（获取/设置ACLs）针对启用分层命名空间（HNS）的帐户。

源代码 | 包（PyPi） | 包（Conda） | API参考文档 | 产品文档 | 示例

入门

先决条件

• 使用此包需要Python 3.8或更高版本。有关更多详细信息，请参阅我们关于Azure SDK for Python版本支持策略的页面。
• 您必须有一个Azure订阅和一个Azure存储帐户才能使用此包。

安装包

使用pip安装Azure DataLake Storage客户端库

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

创建存储帐户

如果您想创建一个新的存储帐户，您可以使用Azure Portal、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和凭据来实例化客户端对象。

获取凭据

您有几种方法可以验证客户端

1. 使用SAS令牌字符串
2. 使用帐户共享访问密钥
3. 使用来自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存储提供四种类型的资源

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

异步客户端

此库包含一个完整的异步API，该API在Python 3.5+上受支持。要使用它，您必须首先安装一个异步传输，例如aiohttp。有关更多信息，请参阅azure-core文档。

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

客户端

DataLake Storage SDK提供了四个不同的客户端来与DataLake服务交互

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

示例

以下部分提供了一些代码片段，涵盖了最常见的存储数据湖任务，包括

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

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

使用连接字符串创建 DataLakeServiceClient，该字符串指向您的 Azure 存储帐户。

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')

可选配置

可以在客户端和每个操作级别传递的可选关键字参数。

重试策略配置

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

• 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。

其他客户端/每个操作配置

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

客户端关键字参数

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

每个操作关键字参数

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

故障排除

一般

DataLake Storage 客户端抛出在 Azure Core 中定义的异常。

此列表可用于参考以捕获抛出的异常。要获取异常的具体错误代码，请使用 error_code 属性，即 exception.error_code。

日志记录

此库使用标准的 logging 库进行日志记录。HTTP 会话的基本信息（URL、头部等）以 INFO 级别记录。

可以通过客户端的 logging_enable 参数启用详细的 DEBUG 级别日志，包括请求/响应体和未脱敏的头部。

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)

下一步

更多示例代码

从我们的 Azure DataLake 示例 开始。

在 SDK 的 GitHub 仓库中，您可以找到几个 DataLake Storage Python SDK 示例。这些示例提供了在处理 DataLake Storage 时遇到的常见场景的示例代码。

• datalake_samples_access_control.py - 常见 DataLake Storage 任务示例

  • 设置文件系统
  • 创建目录
  • 设置/获取目录的访问控制
  • 在目录下创建文件
  • 设置/获取每个文件的访问控制
  • 删除文件系统

• datalake_samples_upload_download.py - 常见 DataLake Storage 任务示例

  • 设置文件系统
  • 创建文件
  • 向文件追加数据
  • 将数据刷新到文件
  • 下载上传的数据
  • 删除文件系统

其他文档

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

贡献

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

提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA 并相应地装饰 PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的 CLA 的所有存储库中这样做一次。

此项目采用了 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或通过 opencode@microsoft.com 联系以获得任何额外的问题或评论。