共用方式為

透過資料移動程式庫傳輸資料

Azure 儲存體資料移動程式庫是跨平台開放原始碼程式庫，專為高效能上傳、下載及複製 Blob 和檔案而設計。 資料移動程式庫提供了無法在適用於 .NET 的 Azure 儲存體用戶端程式庫中使用的便捷方法。 這些方法可讓您設定平行作業數目、追蹤傳輸進度、繼續取消傳輸等等。

數據移動連結庫僅適用於 .NET，且僅支援 Azure Blob 儲存體 和 Azure 檔案儲存體。 在決定是否要使用數據移動連結庫時，您應該考慮這些限制和其他 已知問題 。

如果您要將程式代碼從較舊的 Microsoft.Azure.Storage.DataMovement 連結庫（2.X.X 版）移轉至目前的 Azure.Storage.DataMovement 連結庫（12.X.X 版），請參閱 移轉指南。

API 參考文件 | 原始程式碼 | 套件 （NuGet） |範例：Blobs / Files.Share

必要條件

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。 這些步驟包括封裝安裝、新增 using 指示詞，以及建立已授權的用戶端物件。

安裝套件

從您的項目目錄中，使用 dotnet add package 命令安裝 Azure 儲存體 數據移動用戶端連結庫和 Azure 身分識別客戶端連結庫的套件。 Azure 服務無密碼連線需要 Azure.Identity 套件。

dotnet add package Azure.Storage.DataMovement
dotnet add package Azure.Storage.DataMovement.Blobs
dotnet add package Azure.Identity

若要使用適用於 Azure 檔案儲存體 的擴充連結庫，請安裝 Azure.Storage.DataMovement.Files.Shares 套件：

dotnet add package Azure.Storage.DataMovement.Files.Shares

新增 using 指示詞

若要執行本文中的程式代碼範例，請新增下列 using 指示詞：

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Storage.DataMovement;
using Azure.Storage.DataMovement.Blobs;

如果您使用延伸模組連結庫進行 Azure 檔案儲存體，請新增下列using指示詞：

using Azure.Storage.DataMovement.Files.Shares;

授權

授權機制必須具有執行上傳、下載或複製作業的必要許可權。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料參與者或更高權限。

關於數據移動連結庫

Azure 儲存體 數據行動連結庫包含通用用戶端連結庫，以及適用於 Azure Blob 儲存體 和 Azure 檔案儲存體的擴充連結庫。 通用連結庫提供傳輸數據的核心功能，而擴充連結庫則提供 Blob 記憶體和 Azure 檔案儲存體 特有的功能。 若要深入了解，請參閱下列資源：

建立 TransferManager 物件

TransferManager 是啟動和控制所有類型的傳輸的主要類別，包括上傳、下載和複製。 在本節中，您將瞭解如何建立TransferManager物件，以使用本機文件系統、Blob 記憶體或 Azure 檔案儲存體。

注意

Azure SDK 用戶端管理的最佳做法是將用戶端視為單一，這表示一個類別一次只有一個物件。 對於一組指定的建構函式參數或用戶端選項，不需要保留一個以上的用戶端執行個體。

下列程式代碼示範如何建立 TransferManager 物件：

TransferManager transferManager = new(new TransferManagerOptions());

您可以選擇性地將 TransferManagerOptions 的實例提供給建構函式，這會將特定組態選項套用至對象啟動TransferManager的所有傳輸。 下列組態選項可供使用：

  • CheckpointStoreOptions：選擇性。 定義建立用於儲存傳輸狀態的檢查點的選項，以便繼續傳輸。
  • 診斷：取得傳輸管理員診斷選項。
  • ErrorHandling：選擇性。 定義傳輸期間如何處理錯誤。 預設值為 StopOnAnyFailure。
  • MaximumConcurrency：可在平行傳輸中使用的背景工作角色數目上限。
  • ProvidersForResuming：用於繼續傳輸的傳輸管理員的資源提供者。 預期每個使用中的記憶體提供者都有一個提供者。 若要深入瞭解，請參閱 繼續現有的傳輸。

建立 StorageResource 物件

StorageResource 是所有記憶體資源的基類，包括 Blob 和檔案。 若要建立 StorageResource 物件，請使用下列其中一個提供者類別：

建立 StorageResource Blob 記憶體的物件

下列程式代碼示範如何使用 建立 StorageResource Blob 容器和 Blob Uri的物件：

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

// Get a container resource
StorageResource container = await blobsProvider.FromContainerAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container"));

// Get a block blob resource - default is block blob
StorageResource blockBlob = await blobsProvider.FromBlobAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container/sample-block-blob"),
    new BlockBlobStorageResourceOptions());

// Use a similar approach to get a page blob or append blob resource

您也可以使用來自 Azure.Storage.Blobs 的客戶端物件來建立StorageResource物件。

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobContainerClient blobContainerClient = new(
    new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container"),
    tokenCredential);
StorageResource containerResource = BlobsStorageResourceProvider.FromClient(blobContainerClient);

BlockBlobClient blockBlobClient = blobContainerClient.GetBlockBlobClient("sample-block-blob");
StorageResource blockBlobResource = BlobsStorageResourceProvider.FromClient(blockBlobClient);

// Use a similar approach to get a page blob or append blob resource

啟動新的傳輸

所有傳輸都需要指定來源和目的地。 來源和目的地都是 類型 StorageResource，可以是 StorageResourceContainer 或 StorageResourceItem。 針對指定的傳輸，來源和目的地必須相同。 例如，如果來源是 Blob 容器，目的地必須是 Blob 容器。

您可以呼叫下列方法來啟動新的傳輸：

這個方法會傳 回代表傳送的 TransferOperation 物件。 您可以使用 TransferOperation 物件來監視傳輸進度或取得傳輸識別碼。 傳輸標識碼是繼續傳輸或暫停傳輸所需的傳輸的唯一標識碼。

您可以選擇性地將 TransferOptionsStartTransferAsync 的實例提供給 或 ResumeTransferAsync，這會將特定組態選項套用至特定傳輸。 下列組態選項可供使用：

  • CreationMode：當傳輸遇到已經存在的資源時，設定行為。 在啟動新的傳輸時，預設為 FailIfExists 。 當您繼續傳輸時，預設值可能會有所不同。 針對在傳輸啟動時成功列舉的所有資源， CreationMode 預設為使用的初始值。 對於任何剩餘的資源，會套用一般預設值。
  • InitialTransferSize：第一個範圍要求的大小，以位元組為單位。 單一要求會上傳或下載小於此限制的單一傳輸大小。 傳輸大於此限制的傳輸會繼續以 Size MaximumTransferChunkSize 區塊下載或上傳。 預設值為 32 MiB。 當您繼續傳輸時，預設值是第一次啟動傳輸時所指定的值。
  • MaximumTransferChunkSize：在區塊傳輸數據時，要用於每個區塊的大小上限。 預設值為 4 MiB。 當您繼續傳輸時，預設值是第一次啟動傳輸時所指定的值。
  • ProgressHandlerOptions：選擇性。 變更 ProgressHandler 行為的選項。

範例：將本機目錄上傳至 Blob 容器

下列程式代碼範例示範如何啟動新的傳輸，將本機目錄上傳至 Blob 容器：

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions());

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

string localDirectoryPath = "C:/path/to/directory";
Uri blobContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: LocalFilesStorageResourceProvider.FromDirectory(localDirectoryPath),
    destinationResource: await blobsProvider.FromContainerAsync(blobContainerUri));
await transferOperation.WaitForCompletionAsync();

範例：複製容器或 Blob

您可以使用資料行動連結庫在兩 StorageResource 個實體之間複製。 針對 Blob 資源，傳輸會使用 放置 Blob From URL 作業，以執行伺服器對伺服器複本。

下列程式代碼範例示範如何啟動新的傳輸，將來源 Blob 容器中的所有 Blob 複製到目的地 Blob 容器。 目的地容器必須已經存在。 在此範例中，我們會將 CreationMode 設定為 OverwriteIfExists ，以覆寫已經存在的任何目的地 Blob。 您可以根據應用程式的需求來調整 CreationMode 屬性。

Uri sourceContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/source-container");
Uri destinationContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/dest-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromContainerAsync(
        sourceContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            BlobPrefix = "source/directory/prefix"
        }),
    destinationResource: await blobsProvider.FromContainerAsync(
        destinationContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            // All source blobs are copied as a single type of destination blob
            // Defaults to block blob, if not specified
            BlobType = BlobType.Block,
            BlobPrefix = "destination/directory/prefix"
        }),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

下列程式代碼範例示範如何啟動新的傳輸，將來源 Blob 複製到目的地 Blob。 在此範例中，我們會將 CreationMode 設定為 OverwriteIfExists ，以在目的地 Blob 已經存在時覆寫目的地 Blob。 您可以根據應用程式的需求來調整 CreationMode 屬性。

Uri sourceBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/source-container/source-blob");
Uri destinationBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/dest-container/dest-blob");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromBlobAsync(sourceBlobUri),
    destinationResource: await blobsProvider.FromBlobAsync(destinationBlobUri, new BlockBlobStorageResourceOptions()),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

繼續現有的傳輸

藉由將傳輸進度保存到磁碟，數據移動連結庫可讓您繼續在完成之前失敗的傳輸，否則會取消或暫停。 若要繼續傳輸， TransferManager 必須將 StorageResourceProvider 物件設定為能夠重新組譯從保存的數據傳輸的實例。 您可以使用 ProvidersForResuming TransferManagerOptions 類別的 屬性來指定提供者。

下列程式代碼範例示範如何初始化 TransferManager 能夠繼續本機檔案系統與 Blob 記憶體之間傳輸的物件：

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions()
{
    ProvidersForResuming = new List<StorageResourceProvider>()
    {
        new BlobsStorageResourceProvider(tokenCredential)
    }
});

若要繼續傳輸，請呼叫下列方法：

提供您要繼續之傳輸的傳輸識別碼。 傳輸標識碼是傳輸的唯一標識碼，會在傳輸啟動時傳回做為物件的一部分 TransferOperation 。 如果您不知道傳輸標識碼值，您可以呼叫 TransferManager.GetTransfersAsync 來尋找傳輸及其對應的標識碼。

下列程式代碼範例示範如何繼續傳輸：

TransferOperation resumedTransfer = await transferManager.ResumeTransferAsync(transferId: ID);

注意

如果 TransferCheckpointStoreOptions 設定為 的 TransferManagerOptions一部分，保存傳輸數據的位置與預設位置不同。 若要繼續以自定義檢查點存放區記錄的傳輸，您必須為 TransferManager 繼續傳輸的物件提供相同的檢查點存放區選項。

監視傳輸進度

您可以視應用程式的需求而定，透過數種機制來監視和觀察傳輸。 在本節中，您將瞭解如何使用 TransferOperation 物件監視傳輸進度，以及如何使用 TransferOptions 事件監視傳輸。

範例：使用 TransferOperation 物件監視傳輸進度

您可以使用 方法所StartTransferAsync傳回的物件來監視傳輸進度TransferOperation。 您也可以呼叫 TransferManager.GetTransfersAsync 來列舉物件的所有傳輸 TransferManager 。

下列程式代碼範例示範如何逐一查看所有傳輸，並將每個傳輸的狀態寫入記錄檔：

async Task CheckTransfersAsync(TransferManager transferManager)
{
    await foreach (TransferOperation transfer in transferManager.GetTransfersAsync())
    {
        using StreamWriter logStream = File.AppendText("path/to/log/file");
        logStream.WriteLine(Enum.GetName(typeof(TransferState), transfer.Status.State));
    }
}

TransferStatus 會定義傳送作業的狀態。 TransferStatus 包含下列屬性：

屬性 類型​ 描述
HasCompletedSuccessfully 布林值 表示傳輸是否順利完成，而不會有任何失敗或略過的專案。
HasFailedItems 布林值 表示傳輸是否有任何失敗專案。 如果設定為 true，則傳輸至少有一個失敗專案。 如果設定為 false，則傳輸目前沒有失敗。
HasSkippedItems 布林值 表示傳輸是否有任何略過的專案。 如果設定為 true，則傳輸至少有一個略過的專案。 如果設定為 false，則傳輸目前沒有略過的專案。 如果 SkipIfExists TransferOptions.CreationMode 中未啟用，就不可能略過任何專案。
State TransferState 定義傳輸可以擁有的狀態類型。 如需詳細資訊，請參閱 TransferState 。

範例：使用 TransferOptions 事件監視傳輸進度

您可以接聽 TransferOptions 類別所提供的事件來監視傳輸進度。 TransferOptions實例會傳遞至 方法，StartTransferAsync並提供在傳輸完成、失敗、略過或變更狀態時觸發的事件。

下列程式代碼範例示範如何使用 接聽傳輸完成事件 TransferOptions：

async Task<TransferOperation> ListenToTransfersAsync(
    TransferManager transferManager,
    StorageResource source,
    StorageResource destination)
{
    TransferOptions transferOptions = new();
    transferOptions.ItemTransferCompleted += (TransferItemCompletedEventArgs args) =>
    {
        using (StreamWriter logStream = File.AppendText("path/to/log/file"))
        {
            logStream.WriteLine($"File Completed Transfer: {args.Source.Uri.AbsoluteUri}");
        }
        return Task.CompletedTask;
    };
    return await transferManager.StartTransferAsync(
        source,
        destination,
        transferOptions);
}

使用擴充方法 BlobContainerClient

對於使用BlobContainerClient來自 Azure.Storage.Blobs 類別的現有程式代碼的應用程式，您可以使用擴充方法直接從BlobContainerClient對象開始傳輸。 擴充方法是在 BlobContainerClientExtensions 類別中提供（或適用於 Azure 檔案儲存體 的 ShareDirectoryClientExtensions），並提供使用TransferManager最少程式碼變更的一些優點。 在本節中，您將瞭解如何使用擴充方法來執行物件傳輸 BlobContainerClient 。

如果您還沒有 Azure.Storage.Blobs 套件，請安裝：

dotnet add package Azure.Storage.Blobs

將下列 using 指示詞新增至程式碼檔案頂端：

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

下列程式代碼範例示範如何具現化 BlobContainerClient 名為 sample-container之 Blob 容器的 ：

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobServiceClient client = new BlobServiceClient(
    new Uri("https://<storage-account-name>.blob.core.windows.net"),
    tokenCredential);

BlobContainerClient containerClient = client.GetBlobContainerClient("sample-container");

下列程式代碼範例示範如何使用 將本機目錄內容上傳至 sample-containerUploadDirectoryAsync：

TransferOperation transfer = await containerClient
    .UploadDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

下列程式代碼範例示範如何使用 將 的內容 sample-container 下載至本機目錄 DownloadToDirectoryAsync：

TransferOperation transfer = await containerClient
    .DownloadToDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

若要深入瞭解 的 BlobContainerClient擴充方法，請參閱 BlobContainerClient 上的擴充功能。

後續步驟

  • DataMovement.Blob 和 DataMovement.Files.Shares 的程式碼範例可在適用於 .NET 的 Azure SDK GitHub 存放庫中取得。