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

适用于 JavaScript 的 Azure 存储文件 Data Lake 客户端库 - 版本 12.17.0

项目
05/15/2024

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

此项目提供 JavaScript 中的客户端库，使使用 Data Lake 服务Microsoft Azure 存储变得简单。

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

Create/列出/删除文件系统
Create/Read/List/Update/Delete 路径、目录和文件

关键链接：

入门

目前支持的环境

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

有关更多详细信息，请参阅我们的支持政策。

先决条件

安装包

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

npm install @azure/storage-file-datalake

验证客户端

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

Azure Active Directory
共享密钥
共享访问签名

Azure Active Directory

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

兼容性

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

Web 辅助角色

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

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

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

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

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

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

仅在 Node.js 中提供的功能、接口、类或函数

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

仅在浏览器中提供的功能、接口、类或函数

不可用

JavaScript 捆绑包

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。有关如何执行此操作的详细信息，请参阅捆绑文档。

CORS

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

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

允许的来源： *
允许的谓词：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允许的标头： *
公开的标头： *
最大期限 (秒) ：86400

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

关键概念

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

通过使用的存储帐户DataLakeServiceClient
存储帐户中的 文件系统 ，通过 DataLakeFileSystemClient
文件系统中通过 DataLakeDirectoryClient 或使用的路径DataLakeFileClient

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

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

导入包

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

const AzureStorageDataLake = require("@azure/storage-file-datalake");

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

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

Create data lake 服务客户端

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

with from `DefaultAzureCredential@azure/identity` package

推荐的实例化方法 DataLakeServiceClient

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

设置：参考 - 授权从客户端应用程序使用 Azure Active Directory 访问 blob (data lake) 和队列 - /azure/storage/common/storage-auth-aad-app

注册新的 AAD 应用程序，并授予代表已登录用户访问 Azure 存储的权限。
- 在 azure-portal) 的 Azure Active Directory (中注册新应用程序 - /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 角色 (data Lake) 和队列 - /azure/storage/common/storage-auth-aad-rbac-portal。
- 在 Azure 门户中，转到存储帐户，并从 Access control (IAM) azure 门户) 存储帐户左侧导航栏中的选项卡 (向已注册的 AAD 应用程序分配存储 Blob 数据参与者角色。
示例的环境设置
- 在 AAD 应用程序的概述页中，记下 CLIENT ID 和 TENANT ID。在“证书 & 机密”选项卡中，创建一个机密并记下。
- 确保AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET作为环境变量成功执行示例 (可以利用 process.env) 。

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@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]

使用连接字符串

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

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

使用 `StorageSharedKeyCredential`

或者，通过将 account-name 和 account-key 作为参数传递来实例化 DataLakeServiceClient 。StorageSharedKeyCredential (可以从 azure 门户获取帐户名称和帐户密钥。) [仅在 NODE.JS RUNTIME 中可用]

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@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()。

const { DataLakeServiceClient } = require("@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}`
);

Create新的文件系统

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

列出文件系统

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

或者，不使用 for-await-of：

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  let i = 1;
  let iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  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}`);
      }
    }
  }
}

main();

Create并删除目录

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

创建文件

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  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`);
}

main();

列出文件系统中的路径

类似于列出文件系统。

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  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();
  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) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

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

const { DataLakeServiceClient } = require("@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>"

async function main() {
  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();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file content",
    downloaded
  );

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob: Blob): Promise<string> {
    const fileReader = new FileReader();
    return new Promise<string>((resolve, reject) => {
      fileReader.onloadend = (ev: any) => {
        resolve(ev.target!.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

故障排除

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

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

后续步骤

更多代码示例：

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

曝光数

Share via

适用于 JavaScript 的 Azure 存储文件 Data Lake 客户端库 - 版本 12.17.0

入门

目前支持的环境

先决条件

安装包

验证客户端

Azure Active Directory

兼容性

Web 辅助角色

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

仅在 Node.js 中提供的功能、接口、类或函数

仅在浏览器中提供的功能、接口、类或函数

JavaScript 捆绑包

CORS

关键概念

示例

导入包

Create data lake 服务客户端

with from `DefaultAzureCredential@azure/identity` package

使用连接字符串

使用 `StorageSharedKeyCredential`

使用 SAS 令牌

Create新的文件系统

列出文件系统

Create并删除目录

创建文件

列出文件系统中的路径

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

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

故障排除

后续步骤

贡献

反馈

其他资源

Share via

适用于 JavaScript 的 Azure 存储文件 Data Lake 客户端库 - 版本 12.17.0

入门

目前支持的环境

先决条件

安装包

验证客户端

Azure Active Directory

兼容性

Web 辅助角色

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

仅在 Node.js 中提供的功能、接口、类或函数

仅在浏览器中提供的功能、接口、类或函数

JavaScript 捆绑包

CORS

关键概念

示例

导入包

Create data lake 服务客户端

with from DefaultAzureCredential@azure/identity package

使用 连接字符串

使用 StorageSharedKeyCredential

使用 SAS 令牌

Create新的文件系统

列出文件系统

Create并删除目录

创建文件

列出文件系统中的路径

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

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

故障排除

后续步骤

贡献

反馈

其他资源

with from `DefaultAzureCredential@azure/identity` package

使用连接字符串

使用 `StorageSharedKeyCredential`