上傳具有 TypeScript 的 Blob

發行項
08/05/2024

本文說明如何使用適用於 JavaScript 的 Azure 儲存體用戶端程式庫來上傳 BLOb。您可以從檔案路徑、資料流、緩衝區或文字字串將資料上傳至區塊 Blob。也可以使用索引標籤上傳 Blob。

必要條件

本文中的範例假設您已有設定好要搭配適用於 JavaScript 的 Azure Blob 儲存體用戶端程式庫使用的專案。若要了解如何設定專案，包括套件安裝、匯入模組，以及建立授權的用戶端物件來處理資料資源，請參閱開始使用 Azure Blob 儲存體和 TypeScript (部分機器翻譯)。
授權機制必須具有執行上傳作業的權限。若要深入了解，請參閱下列 REST API 作業的授權指導：
- Put Blob \(英文\)
- 放置區塊

將資料上傳至區塊 Blob

您可以使用下列任一方法，將資料上傳至區塊 Blob：

上傳 (非平行上傳方法)
uploadData
uploadFile (僅適用於 Node.js 執行階段)
uploadStream (僅適用於 Node.js 執行階段)

這些方法中的每一項都可使用 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 時定義用戶端程式庫設定選項。這些選項也可進行調整，以改善效能、增強可靠性，並將成本最佳化。本節中的程式碼範例顯示如何使用 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 的存取層設定為 Hot、Cool、 Cold 或 Archive。若要將存取層設定為 Cold，您必須最少使用用戶端程式庫版本 12.13.0。

若要深入了解存取層，請參閱存取層概觀。

資源

若要深入了解如何使用適用於 JavaScript 和 TypeScript 的 Azure Blob 儲存體用戶端程式庫上傳 BLOb，請參閱下列資源。

REST API 操作

適用於 JavaScript 和 TypeScript 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的語言範例與 REST API 作業進行互動。用來上傳 BLOb 的用戶端程式庫方法會使用下列 REST API 作業：

共用方式為