次の方法で共有


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 サービスと対話するには、ストレージ クライアントのインスタンス (BlobServiceClientContainerClientBlobClient など) を作成する必要があります。 認証の詳細については、 の作成に関する サンプルを参照してください。

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

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

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

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 IDTENANT 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;
  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 固有のガイドの を参照してください。

インプレッション