使用 TypeScript 列出 Blob

项目
09/05/2024

本文介绍如何使用适用于 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: ContainerListBlobsOptions = {
    includeCopy: false,                 // include metadata from previous copies
    includeDeleted: false,              // include deleted blobs 
    includeDeletedWithVersions: false,  // include deleted blobs with versions
    includeLegalHost: false,            // include legal host id  
    includeMetadata: true,              // include custom metadata
    includeSnapshots: true,             // include snapshots
    includeTags: true,                  // include indexable tags
    includeUncommittedBlobs: 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: ContainerClient
): Promise<void> {
  // page size
  const maxPageSize = 2;

  let i = 1;

  // some options for filtering list
  const listOptions: ContainerListBlobsOptions = {
    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: false, // include snapshots
    includeTags: true, // include indexable tags
    includeUncommitedBlobs: false, // include uncommitted blobs
    includeVersions: false, // include all blob version
    prefix: '' // filter by blob name 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
  const marker = response.continuationToken;

  // Passing next marker as continuationToken
  iterator = containerClient
    .listBlobsFlat({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })
    .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)。

使用分层列表

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

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

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

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  virtualHierarchyDelimiter = '/'
): Promise<void> {
  // page size - artificially low as example
  const maxPageSize = 2;

  // some options for filtering list
  const listOptions: ContainerListBlobsOptions = {
    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: false, // include snapshots
    includeTags: true, // include indexable tags
    includeUncommitedBlobs: false, // include uncommitted blobs
    includeVersions: false, // include all blob version
    prefix: '' // filter by blob name prefix
  };

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

  for await (const response of containerClient
    .listBlobsByHierarchy(virtualHierarchyDelimiter, 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 virtualHierarchyDelimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${virtualHierarchyDelimiter}${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 操作：

通过