この記事では、JavaScript 用の Azure Storage クライアント ライブラリを使用して BLOB を一覧表示する方法について説明します。
前提条件
- この記事の例では、JavaScript 用の Azure Blob Storage クライアント ライブラリを操作するように設定されたプロジェクトが、既にあることを前提としています。 パッケージのインストール、モジュールのインポート、データ リソースの操作が認可されたクライアント オブジェクトの作成など、プロジェクトの設定については、「Azure Blob Storage および JavaScript の概要」を参照してください。
- 認可メカニズムには、BLOB を一覧表示するためのアクセス許可が必要です。 詳細については、次の REST API 操作の認可ガイダンスを参照してください。
Blob の一覧表示オプションについて
BLOB をコードから一覧表示する際に、Azure Storage から結果を返す方法を管理するための複数のオプションを指定できます。 各結果セットで返す結果の数を指定し、後続のセットを取得できます。 名前がその文字または文字列から始まる BLOB を返すようにプレフィックスを指定できます。 また、フラット リスト構造 (階層) で BLOB を一覧表示できます。 階層リストでは、フォルダーに整理されたかのように BLOB が返されます。
フラット リストを使用してコンテナー内の BLOB を一覧表示するには、次のメソッドを呼び出します。
階層リストを使用してコンテナー内の BLOB を一覧表示するには、次のメソッドを呼び出します。
- ContainerClient.listBlobsByHierarchy
返される結果の数を管理する
既定では、一覧表示操作から一度に最大 5,000 件の結果が返されますが、各一覧表示操作で返される結果の数は指定できます。 この記事の例は、結果をページに返す方法を示しています。 改ページの概念の詳細は、「Azure SDK for JavaScript を使用した改ページ」をご覧ください。
プレフィックスを使用して結果をフィルター処理する
blob の一覧をフィルターするには、ContainerListBlobsOptions の prefix プロパティに文字列を指定します。 プレフィックス文字列には、1 つ以上の文字を含めることができます。 Azure Storageは、名前がその接頭辞で始まるブロブのみを返します。 たとえば、プレフィックス文字列 sample- を渡すと、名前が sample- で始まる BLOB のみが返されます。
BLOB メタデータまたはその他の情報を含める
結果に blob メタデータを含めるには、ContainerListBlobsOptions で includeMetadata プロパティを true に設定します。 適切なプロパティを true に設定することで、結果にスナップショット、タグ、またはバージョンを含めることもできます。
フラットな一覧表示と階層的な一覧表示
Azure Storage の BLOB は、(従来のファイル システムのような) 階層的なパラダイムではなく、フラットなパラダイムで組織化されます。 ただし、フォルダ構造を模倣するためにブロブを 仮想ディレクトリ に整理することは可能です。 仮想ディレクトリは BLOB 名の一部を形成し、区切り文字によって示されます。
BLOB を仮想ディレクトリに組織化するには、BLOB 名に区切り文字を使用します。 既定の区切り文字はスラッシュ (/) ですが、区切り文字として任意の文字を指定できます。
区切り符を使ってブロブに名前を付ければ、階層的にリストアップすることができます。 階層的な一覧表示操作の場合、Azure Storage は、親オブジェクトの下にあるすべての仮想ディレクトリと BLOB を返します。 従来のファイル システムをプログラムで走査するのと同じような方法で、一覧表示操作を再帰的に呼び出して階層を走査することができます。
フラットな一覧表示を使用する
既定では、一覧表示操作はフラットな一覧表示で BLOB を返します。 フラットな一覧表示では、BLOB は仮想ディレクトリ別に整理されません。
以下の例では、指定されたコンテナ内のブロブをフラットリストでリストアップしています。 次の例では、BLOB スナップショットおよび BLOB メタデータが存在する場合は、それが含まれます:
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}`);
}
}
}
}
出力例は次のようになります。
Blobs flat list (by page):
- Page:
- a1
- a2
- Page:
- folder1/b1
- folder1/b2
- Page:
- folder2/sub1/c
- folder2/sub1/d
注
次に示すサンプル出力では、フラット型名前空間を持つストレージ アカウントがあることを前提としています。 ストレージアカウントで階層的な名前空間機能を有効にすると、ディレクトリは仮想ではありません。 むしろ、それらは具体的で独立したオブジェクトです。 その結果、ディレクトリは長さ 0 の BLOB として一覧に表示されます。
階層型名前空間を使って作業する場合の別のリスト オプションについては、「ディレクトリの内容を一覧表示する (Azure Data Lake Storage)」を参照してください。
階層的な一覧表示を使用する
一覧表示操作を階層的に呼び出すと、Azure Storage は、階層の最初のレベルに仮想ディレクトリと BLOB を返します。
BLOB を階層的に一覧表示するには、次のメソッドを使用します。
次の例では、階層リストを使用して、指定したコンテナー内の BLOB を一覧表示します。 この例では、プレフィックス パラメーターに、最初は空の文字列が設定され、コンテナー内のすべての BLOB が一覧表示されます。 次に、リスト操作を再帰的に呼び出して、仮想ディレクトリ階層を走査し、BLOB を一覧表示します。
// 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}`);
}
}
}
出力例は次のようになります。
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
注
ブロブスナップショットは階層的なリスト操作でリストすることはできません。
Apache Arrow形式のリストブロブ(プレビュー)
Important
Apache Arrow形式でのブロブ表示は現在 プレビュー中です。 このシナリオでは、JavaScript用のAzure Blob Storageクライアントライブラリのベータ(プレビュー)バージョン(例:@azure/storage-blob12.34.0-beta.1以降のプレビューリリース)が必要です。 プレビュー機能は、サービス レベル アグリーメントなしで提供され、運用環境のワークロードには推奨されません。 一部の機能はサポートされていないか、機能が制限されている場合があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。
この機能は既存の List Blobs APIを基盤としています。 デフォルトのXMLを使う代わりに、ワイヤー上のレスポンス形式としてコンパクトで列状の Apache Arrow 形式を使用しています。 コンテナリスティングコールで単一のオプションを設定することで有効化できます。 JavaScript SDKは舞台裏でApache Arrowを解読し、同じブロブアイテムオブジェクトを返します。 この方法は、大規模なコンテナを列挙する際にリストスループットを向上させ、クライアント側のCPUを削減します。 これは、アプリケーションが依存する応答契約を保持します。
Warning
階層的な名前空間(Azure Data Lake Storage)が有効になっているストレージアカウントでは、Apache Arrow形式でのブロブ表示はサポートされていません。
Apache Arrow形式の結果を要求するには、listing optionsの responseFormat プロパティを StorageResponseFormat.Arrowに設定し、そのオプションを ContainerClient.listBlobsFlatに渡します。
@azure/storage-blobからStorageResponseFormat enumをインポートしてください。
以下の例はコンテナ内のブロブを一覧にし、Apache Arrow形式で結果をリクエストします:
const { StorageResponseFormat } = require("@azure/storage-blob");
const options = {
prefix: "FolderA/",
responseFormat: StorageResponseFormat.Arrow,
};
for await (const blob of containerClient.listBlobsFlat(options)) {
console.log("Blob name: " + blob.name);
}
リソース
JavaScript用のAzure Blob Storageクライアントライブラリを使ってブロブをリストアップする方法について詳しく知りたい方は、以下のリソースをご覧ください。
コード サンプル
- この記事からJavaScriptとTypeScriptのコードサンプルをGitHubでご覧いただけます。
REST API の操作
JavaScript用のAzure SDKには、Azure REST APIの上に構築されたライブラリが含まれています。 これらのライブラリを使うことで、馴染みのあるJavaScriptパラダイムを通じてREST API操作とやり取りできます。 BLOB を一覧表示するためのクライアント ライブラリ メソッドは、次の REST API 操作を使用します。
- BLOB の一覧表示 (REST API)