Azure Blob Storage および JavaScript の概要

  • [アーティクル]

この記事では、JavaScript 用 Azure Blob Storage クライアント ライブラリ v12 を使って、Azure Blob Storage に接続する方法について説明します。 接続されると、コードは、Blob Storage サービスのコンテナー、BLOB、機能を使って動作できます。

実行可能な Node.js ファイルとして GitHub からサンプル コード スニペットを入手できます。

API リファレンス | パッケージ (npm) | ライブラリのソース コード | サンプル | フィードバックを送信する

前提条件

プロジェクトの設定

  1. コマンド プロンプトを開き、プロジェクト フォルダーに変更します。 YOUR-DIRECTORY をご使用のフォルダー名に変更してください。

    cd YOUR-DIRECTORY

  2. ディレクトリに package.json ファイルがまだない場合は、プロジェクトを初期化してファイルを作成します。

    npm init -y

  3. JavaScript 用 Azure Blob Storage クライアント ライブラリをインストールします。

    npm install @azure/storage-blob

  4. Microsoft Entra ID を使ってパスワードレス接続を使う場合は、JavaScript 用の Azure ID クライアント ライブラリをインストールします。

    npm install @azure/identity

Blob Storage へのアクセスを承認して接続する

Microsoft Entra ID は、接続 ID (マネージド ID) を管理することで、最も安全な接続を提供します。 このパスワードレス機能を使用すると、コードに格納されているシークレット (キーまたは接続文字列) を必要としないアプリケーションを開発できます。

Azure クラウドへの ID アクセスを設定する

パスワードなしで Azure に接続するには、Azure ID を設定するか、既存の ID を使用する必要があります。 ID が設定されたら、ID に適切なロールを割り当てるようにしてください。

Microsoft Entra ID を使ってパスワードレス アクセスを承認するには、Azure 資格情報を使用する必要があります。 必要な資格情報の種類は、アプリケーションの実行場所によって異なります。 次の表を参考にしてください。

環境 Method
開発者環境 Visual Studio Code
開発者環境 サービス プリンシパル
Azure でホストされるアプリ Azure でホストされるアプリの設定
オンプレミス オンプレミス アプリの設定

ストレージ アカウントのロールを設定する

ストレージ リソースには、接続する予定の ID リソースに割り当てられている次の Azure RBAC ロールが 1 つ以上必要です。 前の手順で作成した各 ID (Azure クラウド、ローカル開発、オンプレミス) に対して、Azure Storage ロールを設定します。

設定を完了した後、各 ID には、少なくとも 1 つの適切なロールが必要です。

  • 次のようなデータ アクセス ロール:

    • ストレージ BLOB データ閲覧者
    • ストレージ BLOB データ共同作成者

  • 次のようなリソース ロール:

    • Reader
    • Contributor

アプリケーションをビルドする

アプリケーションをビルドすると、コードは主に 3 種類のリソースと対話します。

  • ストレージ アカウントは、Azure Storage のデータに対する一意で最上位の名前空間です。
  • コンテナーは、ストレージ アカウント内の BLOB データを整理します。
  • BLOB は、テキストやバイナリ データなどの非構造化データを格納します。

次の図に、これらのリソースの関係を示します。

Diagram of Blob storage architecture

各種類のリソースは、1 つまたは複数の関連付けられた JavaScript クラスによって表されます。

クラス 説明
BlobServiceClient ストレージ アカウントの Blob Storage エンドポイントを表します。
ContainerClient Azure Storage コンテナーとその BLOB を操作できます。
BlobClient Azure Storage の BLOB を操作できます。

BlobServiceClient オブジェクトを作成する

BlobServiceClient オブジェクトは、SDK の最上位のオブジェクトです。 このクライアントを使用すると、サービス、コンテナー、BLOB を操作できます。

Azure ストレージ アカウント ID のロールとローカル環境を設定したら、@azure/identity パッケージを含んだ JavaScript ファイルを作成します。 Blob Storage へのパスワードレス接続を実装するために、DefaultAzureCredential などの資格情報を作成します。 その資格情報を使って、BlobServiceClient オブジェクトで認証します。

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

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

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

dotenv パッケージは、.env ファイルからストレージ アカウント名を読み取るために使用されます。 このファイルをソース コード管理にチェックインすることはしないでください。 ローカル サービス プリンシパルを DefaultAzureCredential 設定の一部として使用した場合、その資格情報のセキュリティ情報も .env ファイル内に格納されます。

Azure の外部で実行するサーバーとクライアントにアプリケーションをデプロイする場合は、ニーズに合わせていずれかの資格情報を作成します。

ContainerClient オブジェクトを作成する

ContainerClient オブジェクトは、BlobServiceClient から、または直接作成できます。

BlobServiceClient から ContainerClient オブジェクトを作成する

BlobServiceClient から ContainerClient オブジェクトを作成する

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

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

ContainerClient を直接作成する

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

dotenv パッケージは、.env ファイルからストレージ アカウント名を読み取るために使用されます。 このファイルをソース コード管理にチェックインすることはしないでください。

BlobClient オブジェクトを作成する

次に示す BlobClient オブジェクトは、ContainerClient から、または直接作成できます。

BLOB クライアントの一覧:

ContainerClient から BlobClient オブジェクトを作成する

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

BlobClient を直接作成する

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

dotenv パッケージは、.env ファイルからストレージ アカウント名を読み取るために使用されます。 このファイルをソース コード管理にチェックインすることはしないでください。

関連項目