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

适用于 Java 的 Azure 文件 Data Lake 客户端库 - 版本 12.17.1

项目
10/25/2023

Azure Data Lake Storage是 Microsoft 针对大数据分析工作负载的优化存储解决方案。 Data Lake Storage Gen2 的一个基本部分是向 Blob 存储添加分层命名空间。分层命名空间将对象/文件组织到目录层次结构中，以便进行有效的数据访问。

源代码 | API 参考文档 | REST API 文档 | 产品文档 | 样品

入门

先决条件

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的 GA 版本。在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后在没有版本标记的依赖项部分中包含直接依赖项。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
  </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
    <version>12.17.1</version>
</dependency>

创建存储帐户

若要创建存储帐户，可以使用 Azure 门户或 Azure CLI。注意：若要使用 data lake，帐户必须启用分层命名空间。

# Install the extension “Storage-Preview”
az extension add --name storage-preview
# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

存储帐户 URL（随后标识为 <your-storage-account-url>）的格式如下 http(s)://<storage-account-name>.dfs.core.windows.net

验证客户端

若要与存储服务交互，需要创建服务客户端类的实例。为此，需要存储帐户的帐户 SAS (共享访问签名) 字符串。有关详细信息，请参阅 SAS 令牌

获取凭据

SAS 令牌

a. 使用以下 Azure CLI 代码片段从存储帐户获取 SAS 令牌。

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

例如：

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. 或者，从 Azure 门户获取帐户 SAS 令牌。

转到存储帐户
Shared access signature从左侧菜单中选择
在设置) 后单击 Generate SAS and connection string (

共享密钥凭据

a. 使用“帐户名称”和“帐户密钥”。帐户名称是存储帐户名称。

转到存储帐户
Access keys从左侧菜单中选择
在下key1/key2复制字段的内容Key

或

b. 使用连接字符串。

转到存储帐户
Access keys从左侧菜单中选择
在下key1/key2复制字段的内容Connection string

关键概念

DataLake Storage Gen2 旨在：

维护数 PB 级信息，同时保持数百吉比特的吞吐量
使你能够轻松管理大量数据

DataLake Storage Gen2 的主要功能包括：

Hadoop 兼容访问
POSIX 权限的超集
在低成本存储容量和事务方面经济高效
用于大数据分析的优化驱动程序

Data Lake Storage Gen2 的一个基本部分是向 Blob 存储添加分层命名空间。分层命名空间将对象/文件组织到目录层次结构中，以便进行有效的数据访问。

过去，基于云的分析必须在性能、管理和安全性方面做出妥协。 Data Lake Storage Gen2 通过以下方式解决这些方面中的每个问题：

优化了性能，因为你不需要将复制或转换数据作为分析的先决条件。分层命名空间极大地提高了目录管理操作的性能，从而提高了整体作业性能。
管理更为容易，因为你可以通过目录和子目录来组织和操作文件。
安全性是可以强制实施的，因为可以在目录或单个文件上定义 POSIX 权限。
由于 Data Lake Storage Gen2 基于低成本的 Azure Blob 存储而构建，因此，可以实现成本效益。这些新增功能进一步降低了在 Azure 上运行大数据分析的总拥有成本。

Data Lake Storage Gen2提供两种类型的资源：

_filesystem通过“DataLakeFileSystemClient”使用的
_path通过“DataLakeFileClient”或“DataLakeDirectoryClient”使用的

ADLS Gen2	Blob
Filesystem	容器
路径 (文件或目录)	Blob

注意：此客户端库不支持分层命名空间 (HNS) 禁用的存储帐户。

URL 格式

路径可使用以下 URL 格式进行寻址：以下 URL 用于文件：

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}

资源 URI 语法

对于存储帐户，datalake 操作的基 URI 仅包括帐户的名称：

https://${myaccount}.dfs.core.windows.net

对于文件系统，基 URI 包括帐户名称和文件系统的名称：

https://${myaccount}.dfs.core.windows.net/${myfilesystem}

对于文件/目录，基 URI 包括帐户的名称、文件系统的名称和路径的名称：

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}

请注意，上述 URI 可能不适用于更高级的方案，例如自定义域名。

示例

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

创建 DataLakeServiceClient
创建 DataLakeFileSystemClient
创建 DataLakeFileClient
创建 DataLakeDirectoryClient
创建文件系统
枚举路径
重命名文件
重命名目录
获取文件属性
获取目录属性
使用 Azure 标识进行身份验证

创建 `DataLakeServiceClient`

DataLakeServiceClient使用sasToken上面生成的创建。

DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

或

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

创建 `DataLakeFileSystemClient`

DataLakeFileSystemClient使用 DataLakeServiceClient创建。

DataLakeFileSystemClient dataLakeFileSystemClient = dataLakeServiceClient.getFileSystemClient("myfilesystem");

或

DataLakeFileSystemClient从上面生成的生成器sasToken创建。

DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .buildClient();

或

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
    .buildClient();

创建 `DataLakeFileClient`

DataLakeFileClient使用 DataLakeFileSystemClient创建。

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");

或

FileClient从上面生成的生成器sasToken创建。

DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("myfile")
    .buildFileClient();

或

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
    .buildFileClient();

创建 `DataLakeDirectoryClient`

DataLakeDirectoryClient使用 DataLakeFileSystemClient获取。

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");

或

DirectoryClient从上面生成的生成器sasToken创建。

DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("mydir")
    .buildDirectoryClient();

或

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
    .buildDirectoryClient();

创建文件系统

使用 DataLakeServiceClient创建文件系统。

dataLakeServiceClient.createFileSystem("myfilesystem");

或

使用 DataLakeFileSystemClient创建文件系统。

dataLakeFileSystemClient.create();

枚举路径

使用 DataLakeFileSystemClient枚举所有路径。

for (PathItem pathItem : dataLakeFileSystemClient.listPaths()) {
    System.out.println("This is the path name: " + pathItem.getName());
}

重命名文件

使用 DataLakeFileClient重命名文件。

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
fileClient.rename("new-file-system-name", "new-file-name");

重命名目录

使用 DataLakeDirectoryClient重命名目录。

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
directoryClient.rename("new-file-system-name", "new-directory-name");

获取文件属性

使用 DataLakeFileClient从文件中获取属性。

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
PathProperties properties = fileClient.getProperties();

获取目录属性

使用 DataLakeDirectoryClient从目录中获取属性。

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
PathProperties properties = directoryClient.getProperties();

使用 Azure 标识进行身份验证

Azure 标识库为使用 Azure 存储进行身份验证提供 Azure Active Directory 支持。

DataLakeServiceClient storageClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

疑难解答

使用此 Java 客户端库与数据湖交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。例如，如果尝试检索存储帐户中不存在的文件系统或路径，则会返回错误 404 ，指示 Not Found。

默认的 HTTP 客户端

默认情况下，所有客户端库都使用 Netty HTTP 客户端。添加上述依赖项会自动将客户端库配置为使用 Netty HTTP 客户端。 HTTP 客户端 Wiki 中详述了如何配置或更改 HTTP 客户端。

默认 SSL 库

默认情况下，所有客户端库均使用 Tomcat 原生 Boring SSL 库来为 SSL 操作启用原生级别性能。 Boring SSL 库是一个 uber jar，其中包含适用于 Linux/macOS/Windows 的原生库。与 JDK 内的默认 SSL 实现相比，它提供更好的性能。有关详细信息（包括如何减小依赖项大小），请参阅 Wiki 的性能优化部分。

后续步骤

在 SDK 的 GitHub 存储库中提供了多个存储 datalake Java SDK 示例。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

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

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

曝光数

通过

适用于 Java 的 Azure 文件 Data Lake 客户端库 - 版本 12.17.1

入门

先决条件

添加包

包括 BOM 文件

包括直接依赖项

创建存储帐户

验证客户端

获取凭据

SAS 令牌

共享密钥凭据

关键概念

URL 格式

资源 URI 语法

示例

创建 `DataLakeServiceClient`

创建 `DataLakeFileSystemClient`

创建 `DataLakeFileClient`

创建 `DataLakeDirectoryClient`

创建文件系统

枚举路径

重命名文件

重命名目录

获取文件属性

获取目录属性

使用 Azure 标识进行身份验证

疑难解答

默认的 HTTP 客户端

默认 SSL 库

后续步骤

贡献

反馈

其他资源

通过

适用于 Java 的 Azure 文件 Data Lake 客户端库 - 版本 12.17.1

入门

先决条件

添加包

包括 BOM 文件

包括直接依赖项

创建存储帐户

验证客户端

获取凭据

SAS 令牌

共享密钥凭据

关键概念

URL 格式

资源 URI 语法

示例

创建 DataLakeServiceClient

创建 DataLakeFileSystemClient

创建 DataLakeFileClient

创建 DataLakeDirectoryClient

创建文件系统

枚举路径

重命名文件

重命名目录

获取文件属性

获取目录属性

使用 Azure 标识进行身份验证

疑难解答

默认的 HTTP 客户端

默认 SSL 库

后续步骤

贡献

反馈

其他资源

创建 `DataLakeServiceClient`

创建 `DataLakeFileSystemClient`

创建 `DataLakeFileClient`

创建 `DataLakeDirectoryClient`