你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 存储 Blob 客户端库 - 版本 12.17.0

项目
01/10/2024

Azure 存储 Blob 是 Microsoft 针对云的对象存储解决方案。 Blob 存储最适合存储巨量的非结构化数据。非结构化数据是不遵循特定数据模型或定义（如文本或二进制数据）的数据。

此项目提供 JavaScript 中的客户端库，以便轻松使用 Microsoft Azure 存储 Blob 服务。

使用此包中的客户端库可以：

获取/设置 Blob 服务属性
创建/列出/删除容器
创建/读取/列出/更新/删除块 Blob
创建/读取/列出/更新/删除页 Blob
创建/读取/列出/更新/删除追加 Blob

关键链接

入门

目前支持的环境

LTS 版本的 Node.js
最新版本的 Safari、Chrome、Edge 和 Firefox。

有关更多详细信息，请参阅我们的支持政策。

先决条件

安装包

安装适用于 JavaScript 的 Azure 存储 Blob 客户端库的首选方法是使用 npm 包管理器。在终端窗口中键入以下内容：

npm install @azure/storage-blob

验证客户端

Azure 存储支持多种方式进行身份验证。若要与 Azure Blob 存储服务交互，需要创建存储客户端的实例（BlobServiceClient例如、 ContainerClient或 BlobClient ）。若要详细了解身份验证，BlobServiceClient请参阅创建的示例。

Azure Active Directory
共享密钥
共享访问签名

Azure Active Directory

Azure Blob 存储服务支持使用 Azure Active Directory 对其 API 的请求进行身份验证。 @azure/identity 包提供应用程序可用于执行此操作的各种凭据类型。有关更多详细信息和示例，请参阅自述文件 @azure/identity 以帮助你入门。

兼容性

此库与 Node.js 和浏览器兼容，并针对 LTS Node.js 版本 (>=8.16.0) 以及 Chrome、Firefox 和 Edge 的最新版本进行验证。

Web 辅助角色

此库要求某些 DOM 对象在浏览器中使用时全局可用，Web 辅助角色默认不提供这些对象。需要对这些库进行填充，以使此库在 Web 辅助角色中正常工作。

有关详细信息，请参阅有关在 Web 辅助角色中使用 Azure SDK for JS 的文档

此库依赖于以下 DOM API，当在 Web 辅助角色中使用时，这些 API 需要加载外部填充：

Node.js 和浏览器之间的差异

Node.js 和浏览器运行时之间存在差异。开始使用此库时，请注意标有 “仅在 NODE.JS RUNTIME 中可用” 或 “仅在浏览器中可用”的 API 或类。

如果 Blob 以或 deflate 格式保存压缩数据gzip，并且其内容编码已相应地设置，则 Node.js 和浏览器之间的下载行为会有所不同。在 Node.js 存储客户端将下载其压缩格式的 Blob，而在浏览器中，数据将以去压缩格式下载。

仅在 Node.js 中提供的功能、接口、类或函数

基于帐户名称和帐户密钥的共享密钥授权
- StorageSharedKeyCredential
共享访问签名 (SAS) 生成
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
并行上传和下载。请注意， BlockBlobClient.uploadData() 在 Node.js 和浏览器中均可用。
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

仅在浏览器中提供的功能、接口、类或函数

并行上传和下载
- BlockBlobClient.uploadBrowserData()

JavaScript 捆绑包

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。有关如何执行此操作的详细信息，请参阅捆绑文档。

CORS

如果需要针对浏览器进行开发，则需要为存储帐户设置跨域资源共享 (CORS) 规则。转到Azure 门户并Azure 存储资源管理器，找到存储帐户，为 blob/队列/文件/表服务 () 创建新的 CORS 规则。

例如，可以创建以下 CORS 设置进行调试。但是，请在生产环境中根据要求仔细自定义设置。

允许的来源：*
允许的谓词：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允许的标头：*
公开的标头：*
最长期限 (秒) ：86400

关键概念

Blob 存储用于：

直接向浏览器提供图像或文档。
存储文件以供分布式访问。
对视频和音频进行流式处理。
向日志文件进行写入。
存储用于备份和还原、灾难恢复及存档的数据。
存储数据以供本地或 Azure 托管服务执行分析。

Blob 存储提供了三种类型的资源：

通过使用的存储帐户BlobServiceClient
存储帐户中的容器，通过 ContainerClient
容器中通过使用的 BlobBlobClient

导入包

若要使用客户端，请将包导入文件：

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

或者，有选择地仅导入所需的类型：

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

创建 Blob 服务客户端

BlobServiceClient需要 Blob 服务的 URL 和访问凭据。它还可以选择接受参数中的 options 某些设置。

with from `DefaultAzureCredential@azure/identity` package

推荐的实例化方法 BlobServiceClient

设置：参考 - 授权从客户端应用程序使用 Azure Active Directory 访问 Blob 和队列 - /azure/storage/common/storage-auth-aad-app

注册新的 AAD 应用程序，并授予代表已登录用户访问 Azure 存储的权限
- 在 azure-portal) 的 Azure Active Directory (中注册新应用程序 - /azure/active-directory/develop/quickstart-register-app
- 在 API permissions 部分中，选择 Add a permission 并选择 Microsoft APIs。
- 选择 Azure Storage 并选中旁边的复选框， user_impersonation 然后单击 Add permissions。这将允许应用程序代表已登录用户访问 Azure 存储。
在 Azure 门户中使用 RBAC 授予对 Azure Blob 数据的访问权限
- Blob 和队列的 RBAC 角色 - /azure/storage/common/storage-auth-aad-rbac-portal。
- 在 Azure 门户中，转到存储帐户，并从 Access control (IAM) azure 门户) 存储帐户左侧导航栏中的选项卡 (向已注册的 AAD 应用程序分配存储 Blob 数据参与者角色。
示例的环境设置
- 在 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]

使用连接字符串

或者，可以使用具有完整连接字符串作为参数的静态方法实例化 BlobServiceClientfromConnectionString() 。 (可从 azure 门户获取连接字符串。) [仅在 NODE.JS RUNTIME 中可用]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

使用 `StorageSharedKeyCredential`

或者，通过将 account-name 和 account-key 作为参数传递来实例化 BlobServiceClient 。StorageSharedKeyCredential (可以从 azure 门户获取帐户名称和帐户密钥。) [仅在 NODE.JS RUNTIME 中可用]

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 门户获取 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();

列出容器

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

有关迭代容器的完整示例，请参阅 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 存储 Blob 客户端库 - 版本 12.17.0

入门

目前支持的环境

先决条件

安装包

验证客户端

Azure Active Directory

兼容性

Web 辅助角色

Node.js 和浏览器之间的差异

仅在 Node.js 中提供的功能、接口、类或函数

仅在浏览器中提供的功能、接口、类或函数

JavaScript 捆绑包

CORS

关键概念

示例

导入包

创建 Blob 服务客户端

with from `DefaultAzureCredential@azure/identity` package

使用连接字符串

使用 `StorageSharedKeyCredential`

使用 SAS 令牌

创建新容器

列出容器

通过上传数据创建 Blob

列出容器中的 Blob

下载 Blob 并将其转换为字符串 (Node.js)

下载 blob 并将其转换为浏览器) (字符串。

疑难解答

后续步骤

贡献

反馈

其他资源

适用于 JavaScript 的 Azure 存储 Blob 客户端库 - 版本 12.17.0

入门

目前支持的环境

先决条件

安装包

验证客户端

Azure Active Directory

兼容性

Web 辅助角色

Node.js 和浏览器之间的差异

仅在 Node.js 中提供的功能、接口、类或函数

仅在浏览器中提供的功能、接口、类或函数

JavaScript 捆绑包

CORS

关键概念

示例

导入包

创建 Blob 服务客户端

with from DefaultAzureCredential@azure/identity package

使用 连接字符串

使用 StorageSharedKeyCredential

使用 SAS 令牌

创建新容器

列出容器

通过上传数据创建 Blob

列出容器中的 Blob

下载 Blob 并将其转换为字符串 (Node.js)

下载 blob 并将其转换为浏览器) (字符串。

疑难解答

后续步骤

贡献

反馈

其他资源

with from `DefaultAzureCredential@azure/identity` package

使用连接字符串

使用 `StorageSharedKeyCredential`