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

适用于 JavaScript 的 Azure 存储文件数据湖客户端库 - 版本 12.27.0

2025-07-24

Azure Data Lake Storage（ADLS）包括使开发人员、数据科学家和分析师能够轻松存储任何大小、形状和速度的数据所需的所有功能，以及跨平台和语言执行所有类型的处理和分析。它消除了引入和存储所有数据的复杂性，同时可以更快地启动和运行批处理、流式处理和交互式分析。

此项目在 JavaScript 中提供了一个客户端库，使用户可以轻松地Microsoft Azure Storage Data Lake 服务使用。

使用此包中的客户端库可以：

创建/列出/删除文件系统
创建/读取/列表/更新/删除路径、目录和文件

key links:

Getting started

当前支持的环境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

See our support policy for more details.

Prerequisites

An Azure subscription
A Storage Account

安装包

安装适用于 JavaScript 的 Azure 存储 Data Lake 客户端库的首选方法是使用 npm 包管理器。在终端窗口中键入以下内容：

npm install @azure/storage-file-datalake

对客户端进行身份验证

Azure 存储支持多种方式进行身份验证。若要与 Azure Data Lake Storage 服务交互，需要创建存储客户端的实例-DataLakeServiceClient、DataLakeFileSystemClient或 DataLakePathClient。请参阅示例，了解如何创建 DataLakeServiceClient，了解有关身份验证的详细信息。

Azure Active Directory
Shared Key
共享访问签名

Azure Active Directory

Azure Data Lake Storage 服务支持使用 Azure Active Directory 对其 API 的请求进行身份验证。 @azure/identity 包提供了应用程序可用于执行此操作的各种凭据类型。有关更多详细信息和示例，请参阅自述文件以获取更多详细信息和示例。

Compatibility

此库与 Node.js 和浏览器兼容，并针对 LTS Node.js 版本（>=8.16.0）和最新版本的 Chrome、Firefox 和 Edge 进行验证。

Web Workers

此库要求某些 DOM 对象在浏览器中使用时全局可用，Web 辅助角色默认不提供这些对象。需要填充这些内容以使此库在 Web 辅助角色中正常工作。

有关详细信息，请参阅我们的文档，了解如何在 Web 辅助角色中使用 Azure SDK for JS

此库依赖于以下 DOM API，这些 API 需要在 Web 辅助角色中使用时加载外部填充：

Node.js 和浏览器之间的差异

Node.js 和浏览器运行时之间存在差异。开始使用此库时，请注意标有 “仅在NODE.JS运行时中可用”的 API 或类 或 “仅在浏览器中可用”。

如果文件保存 gzip 或 deflate 格式的压缩数据，并且其内容编码设置相应，则下载行为在 Node.js 和浏览器之间有所不同。在 Node.js 存储客户端将以压缩格式下载文件，而在浏览器中，数据将以非压缩格式下载。

功能、接口、类或函数仅在 Node.js 中可用

基于帐户名称和帐户密钥的共享密钥授权
- StorageSharedKeyCredential
共享访问签名（SAS）生成
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
并行上传和下载。请注意，Node.js 和浏览器都提供了 DataLakeFileClient.upload()。
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

功能、接口、类或函数仅在浏览器中可用

JavaScript Bundle

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。 For details on how to do this, please refer to our bundling documentation.

CORS

如果需要为浏览器进行开发，则需要为存储帐户设置跨域资源共享（CORS）规则。转到 Azure 门户和 Azure 存储资源管理器，找到存储帐户，为 Blob/队列/文件/表服务创建新的 CORS 规则。

例如，可以创建以下 CORS 设置进行调试。但请根据生产环境中的要求仔细自定义设置。

允许的源： *
允许的谓词：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允许的标头： *
公开的标头： *
最大年龄（秒）：86400

注意：Data Lake 当前共享 Blob 服务的 CORS 设置。

Key concepts

Azure Data Lake Storage Gen2 旨在：

提供多 TB 信息，同时保持数百兆位吞吐量
允许轻松管理大量数据

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 提供三种类型的资源：

The storage account used via DataLakeServiceClient
A file system in the storage account used via DataLakeFileSystemClient
A path in a file system used via DataLakeDirectoryClient or DataLakeFileClient

Azure DataLake Gen2	Blob
Filesystem	Container
路径（文件或目录）	Blob

注意：此客户端库仅支持启用了分层命名空间（HNS）的存储帐户。

导入包

若要使用客户端，请将包导入文件：

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

或者，选择性地仅导入所需的类型：

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

创建 Data Lake 服务客户端

DataLakeServiceClient 需要 Data Lake 服务的 URL 和访问凭据。它还可以选择接受 options 参数中的某些设置。

包含来自 `DefaultAzureCredential` 包的 `@azure/identity`

实例化 DataLakeServiceClient 的建议方法

Notice. Azure Data Lake 当前在进行 AAD OAuth 身份验证期间重复使用与 Blob 相关的角色，例如“存储 Blob 数据所有者”。

设置：参考 - 从客户端应用程序使用 Azure Active Directory 授权访问 blob（数据湖）和队列 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

注册新的 AAD 应用程序，并授予代表已登录用户访问 Azure 存储的权限。
- 在 Azure Active Directory 中注册新应用程序（在 azure-portal 中） - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- 在 API permissions 部分中，选择 Add a permission 并选择 Microsoft APIs。
- 选择 Azure Storage，然后选择 user_impersonation 旁边的复选框，然后单击 Add permissions。这样，应用程序就可以代表已登录用户访问 Azure 存储。
在 Azure 门户中使用 RBAC 授予对 Azure Data Lake 数据的访问权限
- blob（数据湖）和队列的 RBAC 角色 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- 在 Azure 门户中，转到存储帐户，并从 azure 门户的存储帐户左侧导航栏中将 存储 Blob 数据参与者 角色分配给已注册的 AAD Access control (IAM) 应用程序（在 azure 门户的存储帐户左侧导航栏中）。
示例的环境设置
- 在 AAD 应用程序的概述页中，记下 CLIENT ID 和 TENANT ID。在“证书 & 机密”选项卡中，创建机密并记下。
- 请确保已将AZURE_TENANT_ID、AZURE_CLIENT_ID AZURE_CLIENT_SECRET作为环境变量成功执行示例（可以利用 process.env）。

import { DefaultAzureCredential } from "@azure/identity";
import { DataLakeServiceClient } from "@azure/storage-file-datalake";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential,
);

有关使用此方法的完整示例，请参阅 Azure AD 身份验证示例。

[注意 - 上述步骤仅适用于 Node.js]

使用连接字符串

或者，可以使用具有完整连接字符串作为参数的 DataLakeServiceClient 静态方法实例化 fromConnectionString()。（可以从 Azure 门户获取连接字符串。[仅在 NODE.JS RUNTIME 中可用]

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

跟 `StorageSharedKeyCredential`

或者，通过将帐户名称和帐户密钥作为参数传递来实例化具有 DataLakeServiceClient 的 StorageSharedKeyCredential。（可以从 Azure 门户获取帐户名称和帐户密钥。[仅在 NODE.JS RUNTIME 中可用]

import { StorageSharedKeyCredential, DataLakeServiceClient } from "@azure/storage-file-datalake";

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential,
);

使用 SAS 令牌

此外，还可以使用共享访问签名（SAS）实例化 DataLakeServiceClient。可以从 Azure 门户获取 SAS 令牌，也可以使用 generateAccountSASQueryParameters()生成一个。

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

创建新的文件系统

使用 DataLakeServiceClient.getFileSystemClient() 获取文件系统客户端实例，然后创建新的文件系统资源。

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a file system
const fileSystemName = `newfilesystem${new Date().getTime()}`;
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const createResponse = await fileSystemClient.create();
console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);

列出文件系统

使用 DataLakeServiceClient.listFileSystems() 函数通过新的 for-await-of 语法循环访问文件系统：

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
for await (const fileSystem of fileSystems) {
  console.log(`File system ${i++}: ${fileSystem.name}`);
}

或者不使用 for-await-of：

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

此外，通过 byPage()也支持分页列出：

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const response of datalakeServiceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`File System ${i++}: ${fileSystem.name}`);
    }
  }
}

创建和删除目录

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

创建文件

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
const fileClient = fileSystemClient.getFileClient(fileName);
await fileClient.create();
await fileClient.append(content, 0, content.length);
await fileClient.flush(content.length);
console.log(`Create and upload file ${fileName} successfully`);

列出文件系统中的路径

类似于列出文件系统。

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

let i = 1;
const paths = fileSystemClient.listPaths();
for await (const path of paths) {
  console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
}

下载文件并将其转换为字符串（Node.js）

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
const downloadResponse = await fileClient.read();
if (downloadResponse.readableStreamBody) {
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer.
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

下载文件并将其转换为字符串（浏览器）

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account>";
const sas = "<sas token>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
const downloadResponse = await fileClient.read();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

Troubleshooting

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Next steps

更多代码示例：

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.