使用 JavaScript 上傳 Blob

發行項
03/22/2024

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

必要條件

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

將資料上傳至區塊 Blob

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

上傳 (非平行上傳方法)
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 時定義用戶端程式庫設定選項。這些選項也可進行調整，以改善效能、增強可靠性，並將成本最佳化。本節中的程式碼範例顯示如何使用 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);
}

使用索引標籤上傳區塊 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 操作

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