开始使用 Azure Blob 存储和 JavaScript

项目
08/27/2024

本文介绍如何使用适用于 JavaScript 的 Azure Blob 存储客户端库 v12 连接到 Azure Blob 存储。连接后，可以针对 Blob 存储服务的容器、Blob 和功能运行代码。

示例代码片段在 GitHub 中作为可运行 Node.js 文件提供。

API 参考 | 包 (npm) | 库源代码 | 示例

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
Node.js LTS
对于客户端（浏览器）应用程序，需要安装捆绑工具。

设置项目

请打开命令提示符并更改为你的项目文件夹。将 YOUR-DIRECTORY 更改为你的文件夹名称：
```
cd YOUR-DIRECTORY
```
如果目录中没有 package.json 文件，请初始化项目以创建该文件：
```
npm init -y
```
安装适用于 JavaScript 的 Azure Blob 存储客户端库：
```
npm install @azure/storage-blob
```
如果要通过 Microsoft Entra ID 使用无密码连接，请安装适用于 JavaScript 的 Azure 标识客户端库：
```
npm install @azure/identity
```

授予访问权限并连接到 Blob 存储

Microsoft Entra ID 通过管理连接标识（托管标识）提供最安全的连接。此无密码功能使你可以开发不需要存储在代码中的任何机密（密钥或连接字符串）的应用程序。

设置对 Azure 云的标识访问权限

若要在没有密码的情况下连接到 Azure，需要设置 Azure 标识或使用现有标识。设置标识后，请确保为标识分配相应的角色。

若要使用 Microsoft Entra ID 授权无密码访问，需要使用 Azure 凭据。需要哪种类型的凭据取决于应用程序的运行位置。使用此表作为指南。

环境	方法
开发人员环境	Visual Studio Code
开发人员环境	服务主体
Azure 托管的应用	Azure 托管的应用设置
本地	本地应用设置

设置存储帐户角色

你的存储资源需要将以下一个或多个 Azure RBAC 角色分配给你计划连接的标识资源。为在上一步中创建的每个标识设置 Azure 存储角色：Azure 云、本地开发、本地。

完成设置后，每个标识至少需要其中一个相应角色：

数据访问角色 - 例如：
- 存储 Blob 数据读者
- 存储 Blob 数据参与者
资源角色 - 例如：
- 读者
- 参与者

生成应用程序

在生成应用程序时，代码主要与三种类型的资源交互：

存储帐户，它是 Azure 存储数据的唯一顶级命名空间。
容器，用于组织存储帐户中的 Blob 数据。
Blob，用于存储非结构化数据，例如文本和二进制数据。

以下图示显示了这些资源之间的关系。

Blob 存储体系结构的示意图

每种类型的资源由一个或多个关联的 JavaScript 客户端表示：

类	说明
BlobServiceClient	表示存储帐户的 Blob 存储终结点。
ContainerClient	允许操作 Azure 存储容器及其 Blob。
BlobClient	允许操作 Azure 存储 Blob。

创建 BlobServiceClient 对象

BlobServiceClient 对象是 SDK 中的顶级对象。此客户端允许操作服务、容器和 Blob。

设置 Azure 存储帐户标识角色和本地环境后，创建包含 @azure/identity 包的 JavaScript 文件。创建凭据（例如 DefaultAzureCredential），以实现与 Blob 存储的无密码连接。使用该凭据通过 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.chinacloudapi.cn`,
  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 外部运行的服务器和客户端，请创建符合需要的凭据之一。

根据存储帐户名称和帐户密钥创建 StorageSharedKeyCredential。然后将 StorageSharedKeyCredential 传递给 BlobServiceClient 类构造函数以创建客户端。

// connect-with-account-name-and-key.js
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
require('dotenv').config()

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

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.chinacloudapi.cn`,
  sharedKeyCredential
);

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(ex.message));

dotenv 包用于从 .env 文件中读取存储帐户名称和密钥。不应将此文件签入到源代码管理中。

有关如何获取帐户密钥的信息以及正确管理和保护密钥的最佳做法指导，请参阅管理存储帐户访问密钥。

重要

应谨慎使用帐户访问密钥。如果帐户访问密钥丢失或意外放置在不安全的位置，服务可能会变得易受攻击。具有访问密钥的任何人都可以授权针对存储帐户的请求，并且实际上有权访问所有数据。 DefaultAzureCredential 提供增强的安全功能和优势，是管理 Azure 服务授权的推荐方法。

使用 Blob 服务终结点和 SAS 令牌为资源创建 Uri。然后，使用该 Uri 创建 BlobServiceClient。 SAS 令牌是查询字符串中的一系列名称/值对，其格式如下：

https://YOUR-RESOURCE-NAME.blob.core.chinacloudapi.cn?YOUR-SAS-TOKEN

根据用于生成 SAS 令牌的工具，查询字符串 ? 可能已添加到 SAS 令牌。

// connect-with-sas-token.js
const { BlobServiceClient } = require('@azure/storage-blob');
require('dotenv').config()

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

const blobServiceUri = `https://${accountName}.blob.core.chinacloudapi.cn`;

// https://YOUR-RESOURCE-NAME.blob.core.chinacloudapi.cn?YOUR-SAS-TOKEN
const blobServiceClient = new BlobServiceClient(
  `${blobServiceUri}?${sasToken}`,
  null
);

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 文件中读取存储帐户名称和 SAS 令牌。不应将此文件签入到源代码管理中。

若要生成和管理 SAS 令牌，请参阅以下任何文章：

注意

对于使用共享访问签名 (SAS) 的方案，Azure 建议使用用户委托 SAS。用户委派 SAS 通过 Microsoft Entra 凭据（而不是帐户密钥）进行保护。若要了解详细信息，请参阅使用 JavaScript 创建用户委派 SAS。

创建 ContainerClient 对象

可以从 BlobServiceClient 创建 ContainerClient 对象，或直接创建。

从 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.chinacloudapi.cn`;
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.chinacloudapi.cn`;

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

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

const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

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

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

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

重要

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

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

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

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

// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;

// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.chinacloudapi.cn/${containerName}?${sasToken}`;

async function main() {
  try {
    // create container client from SAS token
    const containerClient = new ContainerClient(sasUrl);

    // 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 对象

可以从 ContainerClient 创建下面列出的任何 BlobClient 对象，或直接创建。

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.chinacloudapi.cn`;
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.chinacloudapi.cn`;

// 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
}
*/

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlockBlobClient,
} = 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.chinacloudapi.cn`;
const containerName = `my-container`;
const blobName = `my-blob`;

const fileContentsAsString = "Hello there.";

async function main() {
  try {

    // create blob from BlockBlobClient
    const blockBlobClient = new BlockBlobClient(
      `${baseUrl}/${containerName}/${blobName}`,
      sharedKeyCredential
    );

    // Upload data to the blob  
    await blockBlobClient.upload(
      fileContentsAsString,
      fileContentsAsString.length
    );
    console.log(`blob ${blockBlobClient.url} created`);
  } catch (err) {
    console.log(err);
    throw err;
  }
}

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

重要

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

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

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

// Container and blob must exist prior to running this script
// SAS token must have READ permissions on blob that haven't expired
const containerName = `test`;
const blobName = `my-text-file.txt`;

// Create SAS URL
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
const sasUrl = `https://${accountName}.blob.core.chinacloudapi.cn/${containerName}/${blobName}?${sasToken}`;

// Utility function to convert 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);
  });
}

async function main(){

  // Create a blob client from SAS token
  const client = new BlockBlobClient(sasUrl);

  // Get blob url
  console.log(`blob.url: ${client.url}`);

  // Download file contents
  const result = await client.download();
  const content = await streamToBuffer(result.readableStreamBody);

  // Get results
  return content.toString();
}

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

注意