使用 JavaScript 列出 Blob
本文說明如何使用適用於 JavaScript 的 Azure 儲存體用戶端程式庫來列出 Blob。
必要條件
- 本文中的範例假設您已設定專案,以搭配使用適用於 JavaScript 的 Azure Blob 儲存體用戶端程式庫。 若要了解設定專案,包括套件安裝、匯入模組,以及建立授權的用戶端物件來處理資料資源,請參閱開始使用 Azure Blob 儲存體和 JavaScript。
- 授權機制必須具有列出 Blob 的權限。 若要深入了解,請參閱下列 REST API 作業的授權指引:
關於 Blob 清單選項
當從程式碼列出 Blob 時,即可指定數個選項來管理從 Azure 儲存體傳回結果的方式。 您可指定要在每一組結果中傳回的結果數目,然後擷取後續集合。 您可指定前置詞,以傳回名稱開頭為該字元或字串的 Blob。 也可以使用簡單列表結構或以階層方列出 Blob。 階層式清單會傳回 Blob,就好像這些 Blob 已組織成資料夾一樣。
若要列出儲存體帳戶中的 Blob,請建立 ContainerClient,然後呼叫下列其中一種方法:
- ContainerClient.listBlobsByHierarcy
- ContainerClient.listBlobsFlat
您可以在下列方法中找到相關功能:
- BlobServiceClient.findBlobsByTag
- ContainerClient.findBlobsByTag
管理傳回的結果數目
根據預設,列出作業一次最多會傳回 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 作業:
- 列出 Blob (REST API)
程式碼範例
- 檢視本文中的程式碼範例 (GitHub) (英文)