使用 JavaScript 上传 Blob

项目
08/27/2024

本文介绍如何使用适用于 JavaScript 的 Azure 存储客户端库上传 blob。可以通过文件路径、流式传输、缓冲区或文本字符串将数据上传到块 Blob。还可以上传带有索引标记的 Blob。

先决条件

本文中的示例假设你已经设置了一个项目来使用适用于 JavaScript 的 Azure Blob 存储客户端库。若要了解如何设置项目（包括安装包、导入模块，以及创建授权客户端对象来使用数据资源），请参阅开始使用 Azure Blob 存储和 JavaScript。
授权机制必须具有执行上传操作的权限。若要了解详细信息，请参阅以下 REST API 操作的授权指南：
- 放置 Blob
- 放置块

将数据上传到块 Blob

可以使用以下任一方法将数据上传到块 Blob：

upload（非并行上传方法）
uploadData
uploadFile（仅适用于 Node.js 运行时）
uploadStream（仅适用于 Node.js 运行时）

可以使用 BlockBlobClient 对象调用其中每种方法。

通过文件路径上传块 Blob

以下示例通过本地文件路径上传了块 Blob：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadBlobFromLocalPath(containerClient, blobName, localFilePath){
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

通过流式传输上传块 Blob

以下示例通过创建并上传可读流来上传块 blob：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// readableStream: Readable stream, for example, a stream returned from fs.createReadStream()
async function uploadBlobFromReadStream(containerClient, blobName, readableStream) {
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload data to block blob using a readable stream
  await blockBlobClient.uploadStream(readableStream);
}

通过缓冲区上传块 Blob

以下示例从 Node.js 缓冲区上传块 blob：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// buffer: blob contents as a buffer, for example, from fs.readFile()
async function uploadBlobFromBuffer(containerClient, blobName, buffer) {

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

通过字符串上传块 Blob

以下示例通过字符串上传了块 Blob：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// fileContentsAsString: blob content
async function uploadBlobFromString(containerClient, blobName, fileContentsAsString){
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length);
}

使用配置选项上传块 blob

上传 blob 时，可以定义客户端库配置选项。可以优化这些选项以提高性能、增强可靠性和优化成本。本部分中的代码示例展示了如何使用e BlockBlobParallelUploadOptions 接口设置配置选项，以及如何将这些选项作为参数传递给上传方法调用。

在上传时指定数据传输选项

可以配置 BlockBlobParallelUploadOptions 中的属性以提高数据传输操作的性能。下表列出了可以配置的属性及其说明：

属性	说明
`blockSize`	作为上传操作一部分的每个请求传输的最大块大小。
`concurrency`	在任何给定时间，作为单个并行传输的一部分发出的最大并行请求数量。
`maxSingleShotSize`	如果数据的大小小于或等于此值，则会在单个放置操作中上传，而不是拆分成区块。如果一次性上传数据，则会忽略块大小。默认值为 256 MiB。

以下代码示例演示如何设置 BlockBlobParallelUploadOptions 的值并将选项作为上传方法调用的一部分包含在内。此示例中提供的值不作为建议。若要正确优化这些值，需要考虑应用的特定需求。

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithTransferOptions(containerClient, blobName, localFilePath) {
  // Specify data transfer options
  const uploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  } 

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

若要详细了解如何优化数据传输选项，请参阅优化 JavaScript 的上传和下载性能。

上传带有索引标记的块 blob

Blob 索引标记使用键值标记属性对存储帐户中的数据进行分类。这些标记会自动索引，并作为可搜索的多维索引公开，便于你轻松查找数据。

以下示例使用 BlockBlobParallelUploadOptions 上传设置了索引标记的块 blob：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithIndexTags(containerClient, blobName, localFilePath) {
  // Specify index tags for blob
  const uploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2023-06-01',
    }
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

在上传期间设置 blob 的访问层

可以使用 BlockBlobParallelUploadOptions 接口在上传时设置 Blob 的访问层。以下代码示例演示如何在上传 blob 时设置访问层：

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithAccessTier(containerClient, blobName, localFilePath) {
  // Specify access tier
  const uploadOptions = {
    tier: 'Cool',
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob to cool tier
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

仅允许为块 blob 设置访问层。可以将块 blob 的访问层设置为 Hot、Cool、Cold 或 Archive。若要将访问层设置为 Cold，必须至少使用客户端库版本 12.13.0。

若要详细了解访问层，请参阅访问层概述。

资源

若要详细了解如何使用适用于 JavaScript 的 Azure Blob 存储客户端库来上传 Blob，请参阅以下资源。

REST API 操作

Azure SDK for JavaScript 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 JavaScript 范例与 REST API 操作进行交互。用于上传 blob 的客户端库方法使用以下 REST API 操作：

通过