使用 JavaScript 列出 Blob

아티클
11/26/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。

包括 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)

다음을 통해 공유