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

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.Shars

Prerequisites

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
適用於您作業系統的最新 .NET SDK。請務必取得 SDK，而不是執行階段。

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 .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;

Authorization

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

關於資料移動程式庫

Azure 儲存體資料移動程式庫包含一般用戶端程式庫，以及適用於 Azure Blob 儲存體和 Azure 檔案儲存體的擴充程式庫。一般程式庫提供傳輸資料的核心功能，而擴充程式庫則提供 Blob 儲存體和 Azure 檔案儲存體特定的功能。若要深入了解，請參閱下列資源：

建立 `TransferManager` 物件

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

Note

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

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

TransferManager transferManager = new(new TransferManagerOptions());

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

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

建立 `StorageResource` 物件

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

BlobsStorageResourceProvider：使用此類別來為 Blob 容器、區塊 Blob、附加 Blob 或分頁 Blob 建立StorageResource實例。
ShareFilesStorageResourceProvider：使用此類別來建立 StorageResource 檔案或目錄的實例。
LocalFilesStorageResourceProvider：使用此類別來建立 StorageResource 本機檔案系統的實例。

建立 Blob 儲存體的 `StorageResource` 物件

下列程式碼示範如何使用 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

您也可以使用 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 容器。

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

TransferManager.StartTransferAsync

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

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

CreationMode：設定傳輸遇到已存在的資源時的行為。在啟動新的傳輸時，預設為 FailIfExists。當您繼續傳輸時，預設值可能會有所不同。針對在傳輸啟動時成功列舉的所有資源，CreationMode 預設為使用的初始值。對於任何剩餘的資源，會套用一般預設值。
InitialTransferSize：第一個範圍要求的大小，以位元組為單位。小於此限制的單一傳輸大小，會以單一要求上傳或下載。大於此限制的傳輸會繼續以大小為 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 資源，傳輸會使用從 URL 放置 Blob 作業，這會執行伺服器對伺服器的複製。

下列程式碼範例示範如何啟動新的傳輸，將來源 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 （如果它已經存在）。您可以根據應用程式的需求來調整 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 執行個體來設定。您可以使用 ProvidersForResumingTransferManagerOptions 類別的屬性來指定提供者。

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

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

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

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

TransferManager.ResumeTransferAsync

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

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

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

Note

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

監視傳輸進度

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

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

您可以使用 TransferOperation 方法所傳回的 StartTransferAsync 物件來監視傳輸進度。您也可以呼叫 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 包含下列屬性：

Property	類型	Description
`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 類別的現有程式碼的應用程式，您可以使用延伸模組方法直接從物件開始傳輸。延伸方法會在 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 的 Blob 容器的 sample-container 具現化：

// 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-container 將本機目錄內容上傳至 UploadDirectoryAsync：

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.Blobs 和 DataMovement.Files.Shares 的程式碼範例可在適用於 .NET 的 Azure SDK GitHub 存放庫中使用。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-10