使用 JavaScript 列出 Blob

  • 發行項

本文說明如何使用適用於 JavaScript 的 Azure 儲存體用戶端程式庫來列出 Blob。

必要條件

  • 本文中的範例假設您已有專案設定好要使用適用於 JavaScript 的 Azure Blob 儲存體用戶端程式庫。 若要了解設定專案，包括套件安裝、匯入模組，以及建立授權的用戶端物件來處理資料資源，請參閱開始使用 Azure Blob 儲存體和 JavaScript。
  • 授權機制必須具有列出 Blob 的權限。 若要深入了解，請參閱下列 REST API 作業的授權指引：

關於 Blob 清單選項

當從程式碼列出 Blob 時，即可指定數個選項來管理從 Azure 儲存體傳回結果的方式。 您可指定要在每一組結果中傳回的結果數目，然後擷取後續集合。 您可指定前置詞，以傳回名稱開頭為該字元或字串的 Blob。 也可以使用簡單列表結構或以階層方列出 Blob。 階層式清單會傳回 Blob，就好像這些 Blob 已組織成資料夾一樣。

若要列出儲存體帳戶中的 Blob，請建立 ContainerClient，然後呼叫下列其中一種方法：

您可以在下列方法中找到相關功能：

管理傳回的結果數目

根據預設，列出作業一次最多會傳回 5000 個結果，但您可以指定要讓每個列出作業傳回的結果數目。 本文中顯示的範例會說明如何在頁面中傳回結果。 若要深入了解分頁概念，請參閱使用 Azure SDK for JavaScript 進行分頁。

使用前置詞篩選結果

若要篩選 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 操作

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

程式碼範例

用戶端程式庫資源

另請參閱