使用 JavaScript 列出 Blob

项目
10/04/2023

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

先决条件

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

了解 blob 列出选项

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

若要列出存储帐户中的 blob，请创建 ContainerClient，然后调用以下方法之一：

ContainerClient.listBlobsByHierarcy
ContainerClient.listBlobsFlat

可在以下方法中找到相关功能：

BlobServiceClient.findBlobsByTag
ContainerClient.findBlobsByTag

管理要返回的结果数

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

使用前缀筛选结果

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

const listOptions = {
    includeCopy: false,                 // include metadata from previous copies
    includeDeleted: false,              // include deleted blobs 
    includeDeletedWithVersions: false,  // include deleted blobs with versions
    includeLegalHold: false,            // include legal hold
    includeMetadata: true,              // include custom metadata
    includeSnapshots: true,             // include snapshots
    includeTags: true,                  // include indexable tags
    includeUncommitedBlobs: false,      // include uncommitted blobs
    includeVersions: false,             // include all blob version
    prefix: ''                          // filter by blob name prefix
};

返回元数据

可以通过在includeMetadata列表选项中指定属性来返回包含结果的 Blob 元数据。

平面列表与分层列表

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

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

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

使用平面列出

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

以下示例使用平面列表列出指定容器中的 blob。

async function listBlobsFlatWithPageMarker(containerClient) {

  // page size - artificially low as example
  const maxPageSize = 2;

  let i = 1;
  let marker;

  // some options for filtering list
  const listOptions = {
    includeMetadata: false,
    includeSnapshots: false,
    includeTags: false,
    includeVersions: false,
    prefix: ''
  };

  let iterator = containerClient.listBlobsFlat(listOptions).byPage({ maxPageSize });
  let response = (await iterator.next()).value;

  // Prints blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }

  // Gets next marker
  marker = response.continuationToken;

  // Passing next marker as continuationToken    
  iterator = containerClient.listBlobsFlat().byPage({ 
      continuationToken: marker, 
      maxPageSize: maxPageSize * 2 
  });
  response = (await iterator.next()).value;

  // Prints next blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }
}

示例输出类似于：

Flat listing: 1: a1
Flat listing: 2: a2
Flat listing: 3: folder1/b1
Flat listing: 4: folder1/b2
Flat listing: 5: folder2/sub1/c
Flat listing: 6: folder2/sub1/d

注意

所显示的示例输出假定你有一个带平面命名空间的存储帐户。如果为存储帐户启用了分层命名空间功能，则目录不是虚拟目录。而是具体的独立对象。因此，目录会在列表中显示为零长度 blob。
有关使用分层命名空间时的备用列表选项
，请参阅列出目录内容 (Azure Data Lake Storage Gen2)。

使用分层列表

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

若要以分层方式列出 blob，请调用 BlobContainerClient.listBlobsByHierarchy 方法。

以下示例使用分层列表列出指定容器中的 Blob（其中指定了可选的段大小），并将 Blob 名称写入控制台窗口。

// Recursively list virtual folders and blobs
// Pass an empty string for prefixStr to list everything in the container
async function listBlobHierarchical(containerClient, prefixStr) {

  // page size - artificially low as example
  const maxPageSize = 2;

  // some options for filtering list
  const listOptions = {
    includeMetadata: false,
    includeSnapshots: false,
    includeTags: false,
    includeVersions: false,
    prefix: prefixStr
  };

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

  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 prefix from current virtual folder
        await listBlobHierarchical(containerClient, 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，请参阅以下资源。

REST API 操作

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