使用 JavaScript 列出 Blob

發行項
10/31/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 個結果，但您可以指定要讓每個列出作業傳回的結果數目。本文中顯示的範例會說明如何在頁面中傳回結果。若要深入了解分頁概念，請參閱使用 Azure SDK for JavaScript 進行分頁。

使用前置詞篩選結果

若要篩選 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 元數據存在，則此範例包含 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 操作

適用於 JavaScript 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 JavaScript 範例與 REST API 作業進行互動。用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

列出 Blob (REST API)

共用方式為