Compartir a través de

使用 JavaScript 或 TypeScript 上传 Blob

  • Artículo

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

先决条件

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

将数据上传到块 Blob

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

可以使用 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 transfer options
  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': '2022-07-18',
    }
  }

  // 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 = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    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 操作：

代码示例

查看本文中的代码示例 (GitHub)：

客户端库资源

请参阅

相关内容

  • 本文是适用于 JavaScript/TypeScript 的 Blob 存储开发人员指南的一部分。 要了解详细信息，请参阅构建 JavaScript/TypeScript 应用中的完整开发人员指南文章列表。