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

[アーティクル]
07/24/2024

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 の
共有キーの
Shared Access Signature

Azure Active Directory

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

互換性

このライブラリは、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 とブラウザーのランタイムには違いがあります。このライブラリの使用を開始するときは、"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 経由で使用されるストレージアカウント内の コンテナー
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 を利用できます)。

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;
  let 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;
  let 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;
  let 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に設定します。または、@azure/loggerで setLogLevel を呼び出すことによって、実行時にログを有効にすることもできます。

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

次の手順

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

貢献

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

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

インプレッション

次の方法で共有

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

はじめ

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

Node.js でのみ使用できる機能、インターフェイス、クラス、または関数

ブラウザーでのみ使用できる機能、インターフェイス、クラス、または関数

JavaScript バンドル

CORS

主な概念

例

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

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

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

接続文字列の使用

`StorageSharedKeyCredential`

SAS トークンを使用する

新しいコンテナーを作成する

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

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

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

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

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

トラブルシューティング

次の手順

貢献

その他のリソース

次の方法で共有

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

はじめ

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

前提 条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

Node.js でのみ使用できる機能、インターフェイス、クラス、または関数

ブラウザーでのみ使用できる機能、インターフェイス、クラス、または関数

JavaScript バンドル

CORS

主な概念

例

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

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

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

接続文字列の使用

StorageSharedKeyCredential

SAS トークンを使用する

新しいコンテナーを作成する

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

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

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

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

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

トラブルシューティング

次の手順

貢献

その他のリソース

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

前提条件

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

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

`StorageSharedKeyCredential`