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

使用 JavaScript 列出 Blob

项目
11/01/2024

本文介绍如何使用适用于 JavaScript 的 Azure 存储客户端库列出 blob。

先决条件

本文中的示例假设你已经设置了一个项目来使用适用于 JavaScript 的 Azure Blob 存储客户端库。若要了解如何设置项目（包括安装包、导入模块，以及创建授权客户端对象来使用数据资源），请参阅开始使用 Azure Blob 存储和 JavaScript。
授权机制必须具有列出 blob 的权限。若要了解详细信息，请参阅以下 REST API 操作的授权指南：
- 列出 Blob

了解 blob 列出选项

通过代码列出 Blob 时，可以指定多个选项来管理如何从 Azure 存储返回结果。可以指定要在每个结果集中返回的结果数，然后检索后续结果集。可以指定前缀以返回名称以该字符或字符串开头的 blob。而且，可以在平面列表结构中列出 blob，也可以分层列出 blob。分层列表返回 blob，就像它们被组织到文件夹中一样。

要使用平面列表列出容器中的 Blob，请调用以下方法：

ContainerClient.listBlobsFlat

若要使用分层列表列出容器中的 Blob，请调用以下方法：

ContainerClient.listBlobsByHierarchy

管理要返回的结果数

默认情况下，列表操作一次最多返回 5000 个结果，但你可以指定你所希望的每个列表操作返回的结果数。本文演示的示例说明了如何在页面中返回结果。要详细了解分页概念，请参阅使用适用于 JavaScript 的 Azure SDK 进行分页。

使用前缀筛选结果

要筛选 blob 列表，请在 ContainerListBlobsOptions 中为 prefix 属性指定一个字符串。前缀字符串可以包含一个或多个字符。然后，Azure 存储只返回其名称以该前缀开头的 Blob。例如，如果传递前缀字符串 sample-，则仅返回名称以 sample- 开头的 Blob。

包括 Blob 元数据或其他信息

要在结果中包含 Blob 元数据，请将 includeMetadata 属性设置为 true（作为 ContainerListBlobsOptions 的一部分）。还可通过将相应属性设置为 true，在结果中包含快照、标记或版本。

平面列表与分层列表

Azure 存储中的 Blob 以平面范式进行组织，而不是以分层范式（类似于经典文件系统）进行组织。但是，可以将 Blob 组织到虚拟目录中，以便模拟文件夹结构。虚拟目录构成 blob 名称的一部分，并由分隔符表示。

若要将 blob 组织为虚拟目录，请在 blob 名称中使用分隔符。默认分隔符是正斜杠 (/)，但你可以指定任何字符作为分隔符。

如果使用分隔符来命名 Blob，可以选择以分层方式列出 Blob。对于分层列出操作，Azure 存储将返回父对象下的所有虚拟目录和 Blob。可以递归方式调用列出操作来遍历层次结构，类似于以编程方式遍历经典文件系统。

使用平面列出

默认情况下，列出操作在平面列表中返回 Blob。在平面列表中，Blob 不会按虚拟目录进行组织。

以下示例使用平面列表列出指定容器中的 blob。此示例包含 Blob 快照和 Blob 元数据（如果存在）：

JavaScript
TypeScript

async function listBlobsFlat(containerClient) {

  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list (by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

async function listBlobsFlat(
  containerClient: ContainerClient
): Promise<void> {
  
  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list(by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

示例输出类似于：

Blobs flat list (by page):
- Page:
  - a1
  - a2
- Page:
  - folder1/b1
  - folder1/b2
- Page:
  - folder2/sub1/c
  - folder2/sub1/d

注意

所显示的示例输出假定你有一个带平面命名空间的存储帐户。如果为存储帐户启用了分层命名空间功能，则目录不是虚拟目录。而是具体的独立对象。因此，目录会在列表中显示为零长度 blob。

有关使用分层命名空间时的备用列表选项，请参阅列出目录内容 (Azure Data Lake Storage)。

使用分层列表

以分层方式调用列出操作时，Azure 存储将返回位于层次结构第一级别的虚拟目录和 Blob。

若要按层次结构列出 Blob，请使用以下方法：

BlobContainerClient.listBlobsByHierarchy

以下示例使用分层列表列出了指定容器中的 Blob。在此示例中，前缀参数最初设置为空字符串，以列出容器中的所有 Blob。然后，该示例以递归方式调用列表操作以遍历虚拟目录层次结构和列表 Blob。

JavaScript
TypeScript

// Recursively list virtual folders and blobs
async function listBlobHierarchical(containerClient, delimiter='/') {
  
  const maxPageSize = 20;

  // Some options for filtering list
  const listOptions = {
    prefix: '' // Filter results by blob name prefix   
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {

    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {

      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {

        // Build new delimiter from current and next
        await listBlobHierarchical(containerClient, `${delimiter}${prefix.name}`);
      }
    }

    for (const blob of response.segment.blobItems) {

      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  delimiter = '/'
): Promise<void> {

  const maxPageSize = 20;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    prefix: '' // Filter results by blob name prefix
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {
    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {
      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {
        // Build new delimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${delimiter}${prefix.name}`
        );
      }
    }

    for (const blob of response.segment.blobItems) {
      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

示例输出类似于：

Folder /
   Page 1
        BlobItem: name - a1
        BlobItem: name - a2
   Page 2
Folder /folder1/
   Page 1
        BlobItem: name - folder1/b1
        BlobItem: name - folder1/b2
Folder /folder2/
   Page 1
Folder /folder2/sub1/
   Page 1
        BlobItem: name - folder2/sub1/c
        BlobItem: name - folder2/sub1/d
   Page 2
        BlobItem: name - folder2/sub1/e

注意

在分层列出操作中无法列出 Blob 快照。

资源

若要详细了解如何使用适用于 JavaScript 的 Azure Blob 存储客户端库来列出 Blob，请参阅以下资源。

代码示例

查看本文中的 JavaScript 和 TypeScript 代码示例 (GitHub)

REST API 操作

Azure SDK for JavaScript 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 JavaScript 范例与 REST API 操作进行交互。用于列出 blob 的客户端库方法使用以下 REST API 操作：

列出 Blob (REST API)

通过