通过数据移动库传输数据

Azure 存储数据移动库是一个高性能的跨平台开源库，用于上传、下载和复制 Blob 与文件。 数据移动库提供用于 .NET 的 Azure 存储客户端库中不能提供的便利方法。 通过这些方法，可以设置并行操作的数量、跟踪传输进度、恢复已取消的传输等。

数据移动库仅适用于 .NET，并且仅支持 Azure Blob 存储和 Azure 文件。 You should consider these limitations and other known issues when deciding whether to use the Data Movement library.

If you're migrating code from the older Microsoft.Azure.Storage.DataMovement library (version 2.X.X) to the current Azure.Storage.DataMovement library (version 12.X.X), see the Migration guide.

API 参考文档 | 源代码 | 包 (NuGet) | 示例：Blob / Files.Shares

Prerequisites

• Azure 订阅 - 创建免费帐户
• Azure 存储帐户 - 创建存储帐户
• Latest .NET SDK for your operating system. 确保获取 SDK，而不是运行时。

设置你的环境

如果没有现有项目，请查看本部分，其中介绍如何设置项目来使用适用于 .NET 的 Azure Blob 存储客户端库。 步骤包括安装包、添加 using 指令，以及创建已授权的客户端对象。

Install packages

在项目目录中，使用 dotnet add package 命令安装适用于 Azure 存储数据移动客户端库和 Azure 标识客户端库的包。 The Azure.Identity package is needed for passwordless connections to Azure services.

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

To work with extension library for Azure Files, install the Azure.Storage.DataMovement.Files.Shares package:

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 文件的功能。 若要了解更多信息，请参阅下列资源：

• Azure.Storage.DataMovement
• Azure.Storage.DataMovement.Blobs
• Azure.Storage.DataMovement.Files.Shares

创建 TransferManager 对象

TransferManager is the main class for starting and controlling all types of transfers, including upload, download, and copy. 在本节中，你将了解如何创建一个 TransferManager 对象，以便与本地文件系统、Blob 存储或 Azure 文件配合使用。

以下代码演示如何创建 TransferManager 对象：

TransferManager transferManager = new(new TransferManagerOptions());

You can optionally provide an instance of TransferManagerOptions to the constructor, which applies certain configuration options to all transfers started by the TransferManager object. 以下是可用的配置选项：

• CheckpointStoreOptions: Optional. 定义用于创建保存传输状态的检查点的选项，以便恢复传输。
• Diagnostics: Gets the transfer manager diagnostic options.
• 定义在传输过程中如何处理错误。 默认值为 StopOnAnyFailure。 Default is StopOnAnyFailure.
• MaximumConcurrency: The maximum number of workers that can be used in a parallel transfer.
• ProvidersForResuming: Resource providers for the transfer manager to use in resuming a transfer. 预计每个正在使用的存储提供程序都有一个相应的提供程序。 若要了解详细信息，请参阅恢复现有传输。

创建 StorageResource 对象

StorageResource is the base class for all storage resources, including blobs and files. 若要创建 StorageResource 对象，请使用以下提供程序类之一：

• BlobsStorageResourceProvider: Use this class to create StorageResource instances for a blob container, block blob, append blob, or page blob.
• ShareFilesStorageResourceProvider: Use this class to create StorageResource instances for a file or directory.
• LocalFilesStorageResourceProvider: Use this class to create StorageResource instances for a local file system.

为 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

You can also create a StorageResource object using a client object from Azure.Storage.Blobs.

// 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

This method returns a TransferOperation object that represents the transfer. 可以使用 TransferOperation 对象监控传输进度或获取传输 ID。 传输 ID 是传输的唯一标识符，需要该标识符来恢复传输或暂停传输。

You can optionally provide an instance of TransferOptions to StartTransferAsync or ResumeTransferAsync, which applies certain configuration options to a specific transfer. 以下是可用的配置选项：

• CreationMode: Configures the behavior when a transfer encounters a resource that already exists. 启动新传输时默认为 FailIfExists。 恢复传输时，默认值可能会有所不同。 对于传输开始时成功枚举的所有资源，CreationMode 默认为最初使用的值。 对于任何其余资源，将应用常规默认值。
• InitialTransferSize: The size of the first range request in bytes. 单个传输大小小于此限制时，将通过单个请求上传或下载。 Transfers larger than this limit continue being downloaded or uploaded in chunks of size MaximumTransferChunkSize. 默认值为 32 MiB。 恢复传输时，默认值为首次启动传输时指定的值。
• MaximumTransferChunkSize: The maximum size to use for each chunk when transferring data in chunks. 默认值为 4 MiB。 恢复传输时，默认值为首次启动传输时指定的值。
• ProgressHandlerOptions: Optional. 用于更改 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 容器。 目标容器必须已经存在。 In this example, we set CreationMode to OverwriteIfExists to overwrite any destination blobs that already exist. 可以根据应用的需求调整 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。 In this example, we set CreationMode to OverwriteIfExists to overwrite the destination blob if it already exists. 可以根据应用的需求调整 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 实例，这些实例能够从持久化数据中重组传输。 You can use the ProvidersForResuming property of the TransferManagerOptions class to specify the providers.

以下代码示例演示如何初始化一个能够在本地文件系统和 Blob 存储之间恢复传输的 TransferManager 对象：

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

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

若要恢复传输，请调用以下方法：

• TransferManager.ResumeTransferAsync

提供要恢复的传输的传输 ID。 传输 ID 是传输的唯一标识符，在传输启动时作为 TransferOperation 对象的一部分返回。 If you don't know the transfer ID value, you can call TransferManager.GetTransfersAsync to find the transfer and its corresponding ID.

以下代码示例演示如何恢复传输：

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

监视传输进度

根据应用的需求，可以通过多种机制监视和观察传输。 在本节中，你将了解如何使用 TransferOperation 对象监视传输进度，以及如何使用 TransferOptions 事件监视传输。

示例：使用 TransferOperation 对象监视传输进度

可以使用 TransferOperation 方法返回的 StartTransferAsync 对象监视传输进度。 You can also call TransferManager.GetTransfersAsync to enumerate all transfers for a TransferManager object.

以下代码示例演示如何循环访问所有传输，并将每个传输的状态写入日志文件：

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 defines the status of the transfer job. TransferStatus 包含以下属性：

示例：使用 TransferOptions 事件监视传输进度

You can monitor transfer progress by listening for events provided by the TransferOptions class. The TransferOptions instance is passed to the StartTransferAsync method and provides events that are triggered when a transfer completes, fails, is skipped, or changes status.

以下代码示例演示如何使用 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 使用扩展方法

For applications with existing code that uses the BlobContainerClient class from Azure.Storage.Blobs, you can use extension methods to start transfers directly from a BlobContainerClient object. The extension methods are provided in the BlobContainerClientExtensions class (or ShareDirectoryClientExtensions for Azure Files), and provide some of the benefits of using TransferManager with minimal code changes. 在本节中，你将了解如何使用扩展方法从 BlobContainerClient 对象执行传输。

Install the Azure.Storage.Blobs package if you don't have it already:

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 上的扩展。

Next step

• Code samples for DataMovement.Blobs and DataMovement.Files.Shares are available in the Azure SDK for .NET GitHub repository.