JavaScript 用の Azure Storage BLOB クライアントライブラリ - バージョン 12.29.1

Azure Storage BLOB は、クラウド用の Microsoft のオブジェクトストレージソリューションです。 BLOB ストレージは、大量の非構造化データを格納するために最適化されています。非構造化データとは、テキストやバイナリデータなど、特定のデータモデルや定義に準拠していないデータです。

このプロジェクトは、Microsoft Azure Storage Blob Service を簡単に使用できる JavaScript のクライアントライブラリを提供します。

このパッケージのクライアントライブラリを使用して、次の操作を行います。

Blob Service プロパティの取得/設定
コンテナの作成/一覧表示/削除
ブロック BLOB の作成、読み取り、一覧表示、更新、削除
ページ BLOB の作成、読み取り、一覧表示、更新、削除
追加 BLOB の作成、読み取り、一覧表示、更新、削除

主なリンク

作業の開始

現在サポートされている環境

Node.js の LTS バージョンをする
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、サポートポリシーを参照してください。

Prerequisites

パッケージをインストールする

JavaScript 用の Azure Storage BLOB クライアントライブラリをインストールする場合は、npm パッケージマネージャーを使用することをお勧めします。ターミナルウィンドウに次のように入力します。

npm install @azure/storage-blob

クライアントを認証する

Azure Storage では、いくつかの認証方法がサポートされています。 Azure Blob Storage サービスと対話するには、ストレージクライアントのインスタンス (BlobServiceClient、ContainerClient、BlobClient など) を作成する必要があります。認証の詳細については、の作成に関するサンプルを参照してください。

Azure Active Directory
共有キー
Shared Access Signature

Azure Active Directory

Azure Blob Storage サービスでは、Azure Active Directory を使用して API への要求を認証できます。 @azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。作業を開始するための詳細とサンプルについては、の README を参照してください。

Compatibility

このライブラリは、Node.js とブラウザーと互換性があり、LTS Node.js バージョン (>=8.16.0) と Chrome、Firefox、Edge の最新バージョンに対して検証されます。

Web ワーカー

このライブラリでは、ブラウザーで使用する場合、特定の DOM オブジェクトをグローバルに使用できる必要があります。Web ワーカーは既定では使用できません。 Web ワーカーでこのライブラリを動作させるには、これらをポリフィルする必要があります。

詳細については、Web Worker で Azure SDK for JS を使用するためのドキュメントを参照してください

このライブラリは、Web ワーカーで使用するときに外部ポリフィルを読み込む必要がある次の DOM API に依存します。

Node.js とブラウザーの違い

Node.js とブラウザーのランタイムには違いがあります。このライブラリの使用を開始するときは、"ONLY AVAILABLE IN NODE.JS RUNTIME" または "ONLY AVAILABLE IN BROWSERS"でマークされた API またはクラスに注意してください。

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
経由で使用されるコンテナー内の BLOBBlobClient

Examples

パッケージをインポート
BLOB サービスクライアントを作成する
新しいコンテナーを作成する
コンテナーのを一覧表示する
データをアップロードして BLOB を作成する
コンテナー内の BLOB を一覧表示する
BLOB をダウンロードし、文字列 (Node.js) に変換
BLOB をダウンロードして文字列に変換する (ブラウザー)

パッケージをインポートする

クライアントを使用するには、パッケージをファイルにインポートします。

import * as AzureStorageBlob from "@azure/storage-blob";

または、必要な型のみを選択的にインポートします。

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

BLOB サービスクライアントを作成する

BlobServiceClient には、BLOB サービスへの URL とアクセス資格情報が必要です。また、必要に応じて、options パラメーターの一部の設定を受け入れます。

パッケージからの `DefaultAzureCredential@azure/identity` 使用

BlobServiceClient をインスタンス化するための推奨される方法

セットアップ : リファレンス - クライアントアプリケーションから Azure Active Directory を使用して BLOB とキューへのアクセスを承認する - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

新しい AAD アプリケーションを登録し、サインインしているユーザーの代わりに Azure Storage にアクセスするためのアクセス許可を付与する
- Azure Active Directory(azure-portal)に新しいアプリケーションを登録する - https://learn.microsoft.com/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 ロール - https://learn.microsoft.com/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 を利用できます)。

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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専用です]

接続文字列の使用

または、完全な接続文字列を引数として使用して、BlobServiceClient 静的メソッドを使用して fromConnectionString() をインスタンス化することもできます。 (接続文字列は Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

`StorageSharedKeyCredential`

または、アカウント名とアカウントキーを引数として渡すことによって、BlobServiceClient を使用して StorageSharedKeyCredential をインスタンス化します。 (アカウント名とアカウントキーは、Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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 トークンを生成することもできます。

import { BlobServiceClient } from "@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() を使用してコンテナークライアントインスタンスを取得し、新しいコンテナーリソースを作成します。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

// 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);

コンテナーを一覧表示する

BlobServiceClient.listContainers() 関数を使用して、新しい for-await-of 構文でコンテナーを反復処理します。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

または、for-await-ofを使用せずに:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

さらに、byPage()を使用して一覧表示する場合にも、改ページがサポートされています。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

コンテナーの反復に関する完全なサンプルについては、 samples/v12/typescript/src/listContainers.tsを参照してください。

データをアップロードして BLOB を作成する

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

コンテナー内の BLOB を一覧表示する

コンテナーの一覧表示に似ています。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

BLOB の反復処理に関する完全なサンプルについては、 samples/v12/typescript/src/listBlobsFlat.ts を参照してください。

BLOB をダウンロードして文字列に変換する (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

BLOB をダウンロードして文字列に変換します (ブラウザー)。

ブラウザーでこのライブラリを使用する方法の詳細については、「 JavaScript バンドル」セクションを参照してください。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

単純なシナリオの完全な例は、 samples/v12/typescript/src/sharedKeyAuth.tsにあります。

Troubleshooting

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

次のステップ

その他のコードサンプル:

Contributing

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドをお読みください。

また、ストレージライブラリのテスト環境の設定に関する追加情報については、Storage 固有のガイドのを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-17