使用 TypeScript 上传 Blob

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

先决条件

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

将数据上传到块 Blob

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

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

通过文件路径上传块 Blob

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

async function uploadBlobFromLocalPath(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

通过流式传输上传块 Blob

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

async function uploadBlobFromReadStream(
  containerClient: ContainerClient,
  blobName: string,
  readStream: fs.ReadStream
): Promise<void> {
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadStream(readStream);
}

通过缓冲区上传块 Blob

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

async function uploadBlobFromBuffer(
  containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

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

通过字符串上传块 Blob

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

async function uploadBlobFromString(
  containerClient: ContainerClient,
  blobName: string,
  fileContents: string
): Promise<void> {
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

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

使用配置选项上传块 blob

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

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

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

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

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

async function uploadWithTransferOptions(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  // Specify data transfer options
  const uploadOptions: BlockBlobParallelUploadOptions = {
    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: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

上传带有索引标记的块 blob

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

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

async function uploadBlobWithIndexTags(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  // Specify index tags for blob
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2023-06-01',
    }
  };

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

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

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

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

async function uploadBlobWithAccessTier(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  // Upload blob to 'Cool' access tier
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tier: 'Cool'
  };

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

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

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

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

资源

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

REST API 操作

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

代码示例

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

客户端库资源

请参阅