共用方式為

使用 JavaScript 以非同步排程來複製 Blob

  • 發行項

本文說明如何使用適用於 JavaScript 的 Azure 儲存體用戶端程式庫，以非同步排程來複製 Blob。 您可以從相同儲存體帳戶內的來源、從不同儲存體帳戶中的來源，或從指定 URL 上透過 HTTP GET 要求擷取的任何可存取物件，來複製 Blob。 您也可以中止擱置中的複製作業。

本文涵蓋的用戶端程式庫方法會使用複製 Blob REST API 作業，而且想要以非同步排程執行複製時，可加以使用。 針對您想要將資料移至儲存體帳戶且內含來源物件 URL 的大多數複製案例，請參閱使用 JavaScript 從來源物件 URL 複製 Blob。

必要條件

  • 本文中的範例假設您已有專案設定好要使用適用於 JavaScript 的 Azure Blob 儲存體用戶端程式庫。 若要了解設定專案，包括套件安裝、匯入模組，以及建立授權的用戶端物件來處理資料資源，請參閱開始使用 Azure Blob 儲存體和 JavaScript。
  • 授權機制必須含有執行複製作業或中止擱置中複製的權限。 若要深入了解，請參閱下列 REST API 作業的授權指引：

關於使用非同步排程複製 Blob

Copy Blob 作業可以非同步完成，而且會盡最大努力執行，這表示作業不保證會立即開始或在指定的時間範圍內完成。 複製作業會排程在背景中，並在伺服器具有可用的資源時執行。 如果複製發生在相同的儲存體帳戶內，作業可以同步完成。

Copy Blob 作業可以執行下列任何動作：

  • 將來源 Blob 複製到具有不同名稱的目的地 Blob。 目的地 Blob 可以是相同 Blob 類型 (區塊、附加或分頁) 的現有 Blob，也可以是複製作業所建立的新 Blob。
  • 將來源 Blob 複製到名稱相同的目的地 Blob，藉此取代目的地 Blob。 此類型的複製作業會移除任何未認可的區塊，並覆寫目的地 Blob 的中繼資料。
  • 將 Azure 檔案服務中的來源檔案複製到目的地 Blob。 目的地 Blob 可以是現有的區塊 Blob，也可以是複製作業所建立的新區塊 Blob。 不支援從檔案複製到分頁 Blob 或附加 Blob。
  • 將快照集複製到其基底 Blob 之上。 藉由將快照集升級到基底 Blob 的位置，您可以還原舊版的 Blob。
  • 將快照集複製到具有不同名稱的目的地 Blob。 產生的目的地 Blob 是可寫入的 Blob，而不是快照集。

若要深入了解 Copy Blob 作業的相關資訊，包括屬性、索引標籤、中繼資料和計費，請參閱複製 Blob 備註。

使用非同步排程來複製 Blob

本節概述「適用於 JavaScript 的 Azure 儲存體用戶端程式庫」所提供的方法，以使用非同步排程來執行複製作業。

下列方法會包裝複製 Blob REST API 作業，然後從來源 Blob 開始非同步複製資料：

beginCopyFromURL 方法會傳回長時間執行的作業輪詢器，可讓您無限期等候，直到複製完成為止。

從 Azure 中的來源複製 Blob

如果您要在相同的儲存體帳戶內複製 Blob，作業可以同步完成。 您可以透過 Microsoft Entra ID、共用存取簽章 (SAS) 或帳戶金鑰來授權來源 Blob 的存取權。 如需另一種同步複製作業，請參閱使用 JavaScript 從來源物件 URL 複製 Blob。

如果複製來源是不同儲存體帳戶中的 Blob，作業可以非同步完成。 來源 Blob 必須透過 SAS 權杖公開或授權。 SAS 權杖需要包含讀取 ('r') 權限。 若要深入了解 SAS 權杖，請參閱使用共用存取簽章委派存取權。

下列範例示範使用非同步排程從不同儲存體帳戶複製來源 Blob 的案例。 在此範例中，我們會使用附加的使用者委派 SAS 權杖來建立來源 Blob URL。 此範例示範如何使用用戶端程式庫來產生 SAS 權杖，但您也可以自行提供。 此範例也會示範如何在複製作業期間租用來源 Blob，以避免從不同的用戶端變更 Blob。 Copy Blob 作業會在複製作業開始時儲存來源 Blob 的 ETag 值。 如果在複製作業完成之前變更 ETag 值，則作業會失敗。

async function copyAcrossStorageAccountsAsync(sourceBlob, destinationBlob, blobServiceClient) {
  // Lease the source blob to prevent changes during the copy operation
  const sourceBlobLease = new BlobLeaseClient(sourceBlob);

  // Create a SAS token that's valid for 1 hour
  const sasToken = await generateUserDelegationSAS(sourceBlob, blobServiceClient);
  const sourceBlobSASURL = sourceBlob.url + "?" + sasToken;

  try {
    await sourceBlobLease.acquireLease(-1);

    // Start the copy operation and wait for it to complete
    const copyPoller = await destinationBlob.beginCopyFromURL(sourceBlobSASURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    // Handle the exception
  } finally {
    // Release the lease once the copy operation completes
    await sourceBlobLease.releaseLease();
  }
}

async function generateUserDelegationSAS(sourceBlob, blobServiceClient) {
  // Get a user delegation key for the Blob service that's valid for 1 hour, as an example
  const delegationKeyStart = new Date();
  const delegationKeyExpiry = new Date(Date.now() + 3600000);
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(
    delegationKeyStart,
    delegationKeyExpiry
  );

  // Create a SAS token that's valid for 1 hour, as an example
  const sasTokenStart = new Date();
  const sasTokenExpiry = new Date(Date.now() + 3600000);
  const blobName = sourceBlob.name;
  const containerName = sourceBlob.containerName;
  const sasOptions = {
    blobName,
    containerName,
    permissions: BlobSASPermissions.parse("r"),
    startsOn: sasTokenStart,
    expiresOn: sasTokenExpiry,
    protocol: SASProtocol.HttpsAndHttp
  };

  const sasToken = generateBlobSASQueryParameters(
    sasOptions,
    userDelegationKey,
    blobServiceClient.accountName
  ).toString();

  return sasToken.toString();
}

注意

使用者委派 SAS 權杖可提供更高的安全性，因為它們是以 Microsoft Entra 認證進行簽署，而不是帳戶金鑰。 若要建立使用者委派 SAS 權杖，Microsoft Entra 安全性主體需有適當的權限。 有關授權需求，請參閱取得使用者委派金鑰。

從 Azure 外部的來源複製 Blob

您可以在透過 HTTP GET 要求於指定 URL 擷取的任何來源物件上，執行複製作業，包括 Azure 外部的可存取物件。 下列範例示範從可存取的來源物件 URL 複製 Blob 的案例。

async function copyFromExternalSource(sourceURL, destinationBlob) {
  const copyPoller = await destinationBlob.beginCopyFromURL(sourceURL);
  await copyPoller.pollUntilDone();
}

檢查複製作業的狀態

若要檢查非同步 Copy Blob 作業的狀態，您可以輪詢 getProperties 方法，並檢查複製狀態。

下列程式碼範例會示範如何檢查擱置中複製作業的狀態：

async function checkCopyStatus(destinationBlob) {
  const properties = await destinationBlob.getProperties();
  console.log(properties.copyStatus);
}

中止複製作業

中止擱置中的 Copy Blob 作業會讓目的地 Blob 的長度為零。 不過，目的地 Blob 的中繼資料會包含新值，這可能是從來源 Blob 複製而來的值，或是在複製作業期間明確設定的值。 若要保留複製前的原始中繼資料，請對目的地 Blob 進行快照集，再呼叫其中一個複製方法。

若要中止擱置中的複製作業，請呼叫下列作業：

此方法會包裝中止複製 Blob REST API 作業，這會取消擱置中的 Copy Blob 作業。 下列程式碼範例說明如何中止擱置中的 Copy Blob 作業：

async function abortCopy(destinationBlob) {
  const properties = await destinationBlob.getProperties();

  // Check the copy status and abort if pending
  if (properties.copyStatus === "pending") {
    await destinationBlob.abortCopyFromURL(properties.copyId);
  }
}

資源

若要深入了解如何使用適用於 JavaScript 的 Azure Blob 儲存體用戶端程式庫，透過非同步排程複製 Blob，請參閱下列資源。

REST API 操作

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

程式碼範例

用戶端程式庫資源