JavaScript 用 Azure Storage BLOB クライアント ライブラリ - バージョン 12.26.0
Azure Storage BLOB は、クラウド用の Microsoft のオブジェクト ストレージ ソリューションです。 BLOB ストレージは、大量の非構造化データを格納するために最適化されています。 非構造化データとは、テキストやバイナリ データなど、特定のデータ モデルや定義に準拠していないデータです。
このプロジェクトは、Microsoft Azure Storage Blob Service を簡単に使用できる JavaScript のクライアント ライブラリを提供します。
このパッケージのクライアント ライブラリを使用して、次の操作を行います。
- Blob Service プロパティの取得/設定
- コンテナーの作成/一覧表示/削除
- ブロック BLOB の作成、読み取り、一覧表示、更新、削除
- ページ BLOB の作成、読み取り、一覧表示、更新、削除
- 追加 BLOB の作成、読み取り、一覧表示、更新、削除
キー リンク
はじめ
現在サポートされている環境
- Node.js の LTS バージョンを
する - Safari、Chrome、Edge、Firefox の最新バージョン。
詳細については、サポート ポリシーの を参照してください。
前提 条件
パッケージをインストールする
JavaScript 用の Azure Storage BLOB クライアント ライブラリをインストールする場合は、npm パッケージ マネージャーを使用することをお勧めします。 ターミナル ウィンドウに次のように入力します。
npm install @azure/storage-blob
クライアントを認証する
Azure Storage では、いくつかの認証方法がサポートされています。 Azure Blob Storage サービスと対話するには、ストレージ クライアントのインスタンス (BlobServiceClient
、ContainerClient
、BlobClient
など) を作成する必要があります。 認証の詳細については、
Azure Active Directory
Azure Blob Storage サービスでは、Azure Active Directory を使用して API への要求を認証できます。
@azure/identity
パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。 作業を開始するための詳細とサンプルについては、
互換性
このライブラリは、Node.js とブラウザーと互換性があり、LTS Node.js バージョン (>=8.16.0) と Chrome、Firefox、Edge の最新バージョンに対して検証されます。
Web Worker
このライブラリでは、ブラウザーで使用する場合、特定の DOM オブジェクトをグローバルに使用できる必要があります。Web ワーカーは既定では使用できません。 Web ワーカーでこのライブラリを動作させるには、これらをポリフィルする必要があります。
詳細については、Web Worker で Azure SDK for JS を使用するための ドキュメントを参照してください
このライブラリは、Web ワーカーで使用するときに外部ポリフィルを読み込む必要がある次の DOM API に依存します。
Node.js とブラウザーの違い
Node.js とブラウザーのランタイムには違いがあります。 このライブラリの使用を開始するときは、
- BLOB が圧縮されたデータを
gzip
またはdeflate
形式で保持し、それに応じてコンテンツ エンコードが設定されている場合、ダウンロード動作は Node.js とブラウザーで異なります。 Node.js ストレージ クライアントでは、BLOB は圧縮形式でダウンロードされますが、ブラウザーではデータは圧縮解除形式でダウンロードされます。
Node.js でのみ使用できる機能、インターフェイス、クラス、または関数
- アカウント名とアカウント キーに基づく共有キーの承認
StorageSharedKeyCredential
- Shared Access Signature (SAS) の生成
generateAccountSASQueryParameters()
generateBlobSASQueryParameters()
- 並列アップロードとダウンロード。
BlockBlobClient.uploadData()
は、Node.js とブラウザーの両方で使用できます。BlockBlobClient.uploadFile()
BlockBlobClient.uploadStream()
BlobClient.downloadToBuffer()
BlobClient.downloadToFile()
ブラウザーでのみ使用できる機能、インターフェイス、クラス、または関数
- 並列アップロードとダウンロード
BlockBlobClient.uploadBrowserData()
JavaScript バンドル
ブラウザーでこのクライアント ライブラリを使用するには、まず、バンドルを使用する必要があります。 これを行う方法の詳細については、
CORS
ブラウザー用に開発する必要がある場合は、ストレージ アカウント クロスオリジン リソース共有 (CORS) 規則を設定する必要があります。 Azure portal と Azure Storage Explorer に移動し、ストレージ アカウントを見つけ、BLOB/キュー/ファイル/テーブル サービス用の新しい CORS ルールを作成します。
たとえば、デバッグ用に次の CORS 設定を作成できます。 ただし、運用環境の要件に合わせて設定を慎重にカスタマイズしてください。
- 許可される配信元: *
- 使用できる動詞: DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
- 許可されるヘッダー: *
- 公開されたヘッダー: *
- 最長有効期間 (秒): 86400
主な概念
BLOB ストレージは、次の目的で設計されています。
- イメージまたはドキュメントをブラウザーに直接提供する。
- 分散アクセス用のファイルの格納。
- ストリーミング ビデオとオーディオ。
- ログ ファイルへの書き込み。
- バックアップと復元、ディザスター リカバリー、アーカイブ用のデータを格納する。
- オンプレミスまたは Azure でホストされるサービスによる分析用のデータの格納。
Blob Storage には、次の 3 種類のリソースが用意されています。
-
ストレージ アカウント
BlobServiceClient
経由で使用されます -
ContainerClient
経由で使用されるストレージ アカウント内の コンテナー -
BlobClient
経由で使用されるコンテナー内の BLOB
例
- パッケージ をインポート
- BLOB サービス クライアント を作成する
- 新しいコンテナー を作成する
- コンテナーの を一覧表示する
- データ をアップロードして BLOB を作成する
- コンテナー 内の BLOB を一覧表示する
- BLOB をダウンロードし、文字列 (Node.js) に変換
- BLOB をダウンロードして文字列に変換する (ブラウザー)
パッケージをインポートする
クライアントを使用するには、パッケージをファイルにインポートします。
const AzureStorageBlob = require("@azure/storage-blob");
または、必要な型のみを選択的にインポートします。
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
BLOB サービス クライアントを作成する
BlobServiceClient
には、BLOB サービスへの URL とアクセス資格情報が必要です。 また、必要に応じて、options
パラメーターの一部の設定を受け入れます。
パッケージからの DefaultAzureCredential
@azure/identity
使用
BlobServiceClient
をインスタンス化するための推奨される方法
セットアップ : リファレンス - クライアント アプリケーションから Azure Active Directory を使用して BLOB とキューへのアクセスを承認する - /azure/storage/common/storage-auth-aad-app
新しい AAD アプリケーションを登録し、サインインしているユーザーの代わりに Azure Storage にアクセスするためのアクセス許可を付与する
- Azure Active Directory (azure-portal) に新しいアプリケーションを登録する - /azure/active-directory/develop/quickstart-register-app
- [
API permissions
] セクションで、[Add a permission
] を選択し、[Microsoft APIs
] を選択します。 -
Azure Storage
を選択し、[user_impersonation
] の横にあるチェックボックスをオンにして、[Add permissions
] をクリックします。 これにより、アプリケーションはサインインしているユーザーの代わりに Azure Storage にアクセスできるようになります。
Azure Portal で RBAC を使用して Azure BLOB データへのアクセスを許可する
- BLOB とキューの RBAC ロール - /azure/storage/common/storage-auth-aad-rbac-portal。
- Azure portal で、ストレージ アカウントに移動し、ストレージ BLOB データ共同作成者 ロールを 、(azure-portal のストレージ アカウントの左側のナビゲーション バーにある)
Access control (IAM)
タブから登録済みの AAD アプリケーションに割り当てます。
サンプルの環境のセットアップ
- AAD アプリケーションの概要ページで、
CLIENT ID
とTENANT ID
をメモします。 [証明書 & シークレット] タブでシークレットを作成し、下にメモします。 - サンプルを正常に実行するための環境変数としてAZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRETしていることを確認します (process.env を利用できます)。
- AAD アプリケーションの概要ページで、
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
この方法を使用した完全な例については、Azure AD 認証のサンプル を参照してください。
[注 - 上記の手順は Node.js専用です]
接続文字列の使用
または、完全な接続文字列を引数として使用して、fromConnectionString()
静的メソッドを使用して BlobServiceClient
をインスタンス化することもできます。 (接続文字列は Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]
const { BlobServiceClient } = require("@azure/storage-blob");
const connStr = "<connection string>";
const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);
StorageSharedKeyCredential
または、アカウント名とアカウント キーを引数として渡すことによって、StorageSharedKeyCredential
を使用して BlobServiceClient
をインスタンス化します。 (アカウント名とアカウント キーは、Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
sharedKeyCredential
);
SAS トークンを使用する
また、共有アクセス署名 (SAS) を使用して BlobServiceClient
をインスタンス化することもできます。 Azure Portal から SAS トークンを取得することも、generateAccountSASQueryParameters()
を使用して SAS トークンを生成することもできます。
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
新しいコンテナーを作成する
BlobServiceClient.getContainerClient()
を使用してコンテナー クライアント インスタンスを取得し、新しいコンテナー リソースを作成します。
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}
main();
コンテナーを一覧表示する
BlobServiceClient.listContainers()
関数を使用して、新しい for-await-of
構文でコンテナーを反復処理します。
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
console.log(`Container ${i++}: ${container.name}`);
}
}
main();
または、for-await-of
を使用せずに:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
const iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
console.log(`Container ${i++}: ${containerItem.value.name}`);
containerItem = await iter.next();
}
}
main();
さらに、byPage()
を使用して一覧表示する場合にも、改ページがサポートされています。
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
if (response.containerItems) {
for (const container of response.containerItems) {
console.log(`Container ${i++}: ${container.name}`);
}
}
}
}
main();
コンテナーの反復処理に関する完全なサンプルについては、サンプル/v12/typescript/src/listContainers.tsを参照してください。
データをアップロードして BLOB を作成する
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const content = "Hello world!";
const blobName = "newblob" + new Date().getTime();
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}
main();
コンテナー内の BLOB を一覧表示する
コンテナーの一覧表示に似ています。
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
console.log(`Blob ${i++}: ${blob.name}`);
}
}
main();
BLOB の反復処理に関する完全なサンプルについては、サンプル/v12/typescript/src/listBlobsFlat.tsを参照してください。
BLOB をダウンロードして文字列に変換する (Node.js)
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
const blobName = "<blob name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = (
await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
).toString();
console.log("Downloaded blob content:", downloaded);
// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream) {
return new Promise((resolve, reject) => {
const chunks = [];
readableStream.on("data", (data) => {
chunks.push(data instanceof Buffer ? data : Buffer.from(data));
});
readableStream.on("end", () => {
resolve(Buffer.concat(chunks));
});
readableStream.on("error", reject);
});
}
}
main();
BLOB をダウンロードして文字列に変換します (ブラウザー)。
ブラウザーでこのライブラリを使用する方法の詳細については、「JavaScript バンドルの」セクションを参照してください。
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
console.log("Downloaded blob content", downloaded);
// [Browsers only] A helper method used to convert a browser Blob into string.
async function blobToString(blob) {
const fileReader = new FileReader();
return new Promise((resolve, reject) => {
fileReader.onloadend = (ev) => {
resolve(ev.target.result);
};
fileReader.onerror = reject;
fileReader.readAsText(blob);
});
}
}
main();
単純なシナリオの完全な例は、サンプル/v12/typescript/src/sharedKeyAuth.tsにあります。
トラブルシューティング
ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL
環境変数を info
に設定します。 または、setLogLevel
で @azure/logger
を呼び出すことによって、実行時にログを有効にすることもできます。
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
次の手順
その他のコード サンプル:
貢献
このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイド を参照してください。
また、ストレージ ライブラリのテスト環境の設定に関する追加情報については、Storage 固有のガイドの を参照してください。
Azure SDK for JavaScript