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

[アーティクル]
11/10/2023

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

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

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

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

キーリンク

はじめに

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

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

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

前提条件

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

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

npm install @azure/storage-blob

クライアントを認証する

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

Azure Active Directory
共有キー
共有アクセス署名

Azure Active Directory

Azure Blob Storage サービスでは、Azure Active Directory を使用して API に対する要求を認証できます。 @azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。作業を開始するための @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 とブラウザーのランタイムには違いがあります。このライブラリの使用を開始するときは、 "NODE.JS ランタイムでのみ使用可能" または "ブラウザーでのみ使用可能 " でマークされた API またはクラス に注意してください。

BLOB が圧縮データをまたは deflate 形式でgzip保持し、そのコンテンツエンコードがそれに応じて設定されている場合、ダウンロード動作は 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 バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず bundler を使用する必要があります。これを行う方法の詳細については、バンドルに関するドキュメントを参照してください。

CORS

ブラウザー用に開発する必要がある場合は、ストレージアカウントのクロスオリジンリソース共有 (CORS) ルールを設定する必要があります。 Azure portalに移動してAzure Storage Explorer、ストレージアカウントを見つけ、BLOB/キュー/ファイル/テーブルサービスの新しい CORS ルールを作成します。

たとえば、デバッグ用に次の CORS 設定を作成できます。ただし、運用環境の要件に合わせて設定を慎重にカスタマイズしてください。

許可される配信元: *
使用できる動詞: DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
許可されるヘッダー: *
公開されているヘッダー: *
最大経過時間 (秒): 86400

主要な概念

Blob Storage は、次の用途に適しています。

画像またはドキュメントをブラウザーに直接配信する。
分散アクセス用にファイルを格納する。
ビデオおよびオーディオをストリーミング配信する。
ログファイルに書き込む。
バックアップと復元、ディザスターリカバリー、アーカイブのためのデータを格納する。
オンプレミスサービスまたは Azure ホステッドサービスで分析するデータを格納する。

Blob Storage には、3 種類のリソースがあります。

によって使用されるストレージアカウントBlobServiceClient
によって使用されるストレージアカウント内のコンテナーContainerClient
によって使用されるコンテナー内の BLOBBlobClient

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

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

const AzureStorageBlob = require("@azure/storage-blob");

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

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

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

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

をインスタンス化するための推奨される方法 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 で、ストレージアカウントに移動し、(azure-portal のストレージアカウントの左側のナビゲーションバーにある) タブからAccess control (IAM)登録済みの AAD アプリケーションにストレージ BLOB データ共同作成者ロールを割り当てます。
サンプルの環境のセットアップ
- AAD アプリケーションの概要ページで、と TENANT IDをCLIENT 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`

または、account-name と StorageSharedKeyCredential account-key を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 トークンを使用する

また、Shared Access Signature (SAS) を使用してをインスタンス化 BlobServiceClient することもできます。 Azure Portal から SAS トークンを取得するか、を使用して SAS トークンを generateAccountSASQueryParameters()生成できます。

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

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

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

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

コンテナーの反復処理に関する完全なサンプルについては、 samples/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 の反復処理に関する完全なサンプルについては、「 samples/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();

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

トラブルシューティング

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

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

setLogLevel("info");

次のステップ

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

共同作成

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

ストレージライブラリのテスト環境を設定する方法の詳細については、「ストレージ固有のガイド」も参照してください。

インプレッション数

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

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主要な概念

例

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

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

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

接続文字列の使用

を使用する `StorageSharedKeyCredential`

SAS トークンを使用する

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

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

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

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

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

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

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

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

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主要な概念

例

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

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

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

接続文字列の使用

を使用する StorageSharedKeyCredential

SAS トークンを使用する

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

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

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

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

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

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

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

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

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

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

を使用する `StorageSharedKeyCredential`