データ移動ライブラリを使用してデータを転送する

Azure Storage データ移動ライブラリは、BLOB およびファイルをハイ パフォーマンスでアップロード、ダウンロード、およびコピーできるように設計された、クロスプラットフォームのオープンソース ライブラリです。 データ移動ライブラリには、.NET 用の Azure Storage クライアント ライブラリでは使用できない便利なメソッドが用意されています。 これらのメソッドを使用すると、並列操作数を設定したり、転送の進行状況を追跡したり、取り消された転送を再開したりすることができます。

データ移動ライブラリは .NET でのみ使用でき、Azure Blob Storage と Azure Files のみをサポートします。 データ移動ライブラリを使用するかどうかを決定する際には、これらの制限やその他の既知の問題を考慮する必要があります。

以前の Microsoft.Azure.Storage.DataMovement ライブラリ (バージョン 2.X.X) から現在の Azure.Storage.DataMovement ライブラリ (バージョン 12.X.X) にコードを移行する場合は、「移行ガイド」を参照してください。

API リファレンス ドキュメント | ソース コード | パッケージ (NuGet) | サンプル: Blobs / Files.Shares

前提条件

• Azure サブスクリプション - 無料アカウントを作成する
• Azure Storage アカウント - ストレージ アカウントの作成
• 使用するオペレーティング システム用の最新の .NET SDK。 ランタイムではなく、必ず SDK を入手してください。

環境を設定する

既存のプロジェクトがない場合、このセクションでは、.NET 用 Azure Blob Storage クライアント ライブラリを使用するようにプロジェクトを設定する方法について説明します。 このステップには、パッケージのインストール、usingディレクティブの追加、承認されたクライアント オブジェクトの作成が含まれます。

パッケージをインストールする

プロジェクト ディレクトリから、dotnet add package コマンドを使用して、Azure Storage データ移動クライアント ライブラリと Azure Identity クライアント ライブラリのパッケージをインストールします。 Azure サービスのパスワードレスの接続には、Azure.Identity パッケージが必要です。

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

Azure Files の拡張ライブラリを使用するには、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 Files の拡張ライブラリを使用している場合は、次の using ディレクティブを追加します。

using Azure.Storage.DataMovement.Files.Shares;

承認

認可メカニズムには、アップロード、ダウンロード、またはコピー操作を実行するために必要なアクセス許可が必要です。 Microsoft Entra ID を使用した認可 (推奨) には、Azure RBAC 組み込みロールのストレージ BLOB データ共同作成者以上が必要です。

データ移動ライブラリについて

Azure Storage データ移動ライブラリは、共通クライアント ライブラリと、Azure Blob Storage および Azure Files 用の拡張ライブラリで構成されています。 共通ライブラリはデータ転送のコア機能を提供し、拡張ライブラリは Blob Storage と Azure Files に固有の機能を提供します。 詳細については、次のリソースを参照してください。

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

TransferManager オブジェクトを作成します

TransferManager は、アップロード、ダウンロード、コピーなど、すべての種類の転送を開始および制御するためのメイン クラスです。 このセクションでは、ローカル ファイル システム、Blob Storage、または Azure Files を操作するための TransferManager オブジェクトを作成する方法について説明します。

Note

Azure SDK クライアント管理のベスト プラクティスは、クライアントをシングルトンとして扱うことです。つまり、クラスには一度に 1 つのオブジェクトだけを含めます。 コンストラクター パラメーターまたはクライアント オプションの特定のセットに対して、クライアントのインスタンスを複数保持する必要はありません。

次のコードは、TransferManager オブジェクトを作成する方法を示しています。

TransferManager transferManager = new(new TransferManagerOptions());

必要に応じて、コンストラクターに TransferManagerOptions のインスタンスを指定できます。これにより、TransferManager オブジェクトによって開始されたすべての転送に特定の構成オプションが適用されます。 次の構成オプションを使用できます。

• CheckpointStoreOptions: 省略可能。 転送を再開できるように、転送状態の保存に使用するチェックポイントを作成するためのオプションを定義します。
• Diagnostics: 転送マネージャーの診断オプションを取得します。
• ErrorHandling: 省略可能。 転送中のエラーの処理方法を定義します。 既定値は StopOnAnyFailure です。
• MaximumConcurrency: 並列転送で使用できるワーカーの最大数。
• ProvidersForResuming: 転送マネージャーが転送を再開する際に使用するリソース プロバイダー。 使用中の記憶域プロバイダーごとに 1 つのプロバイダーが必要です。 詳細については、「既存の転送を再開する」を参照してください。

StorageResource オブジェクトを作成します

StorageResource は、BLOB やファイルを含むすべてのストレージ リソースの基本クラスです。 StorageResource オブジェクトを作成するには、次のいずれかのプロバイダー クラスを使用します。

• BlobsStorageResourceProvider: このクラスは、BLOB コンテナー、ブロック BLOB、追加 BLOB、またはページ BLOB 用の StorageResource インスタンスを作成するために使用します。
• ShareFilesStorageResourceProvider: このクラスは、ファイルまたはディレクトリ用の StorageResource インスタンスを作成するために使用します。
• LocalFilesStorageResourceProvider: このクラスは、ローカル ファイル システム用の StorageResource インスタンスを作成するために使用します。

Blob Storage 用の StorageResource オブジェクトを作成する

次のコードは、Uri を使用して BLOB コンテナーおよび BLOB 用の StorageResource オブジェクトを作成する方法を示しています。

// 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 コンテナーである必要があります。

次のメソッドを呼び出すことで、新しい転送を開始できます。

• TransferManager.StartTransferAsync

このメソッドは、転送を表す TransferOperation オブジェクトを返します。 TransferOperation オブジェクトを使用して、転送の進行状況を監視したり、転送 ID を取得したりできます。 転送 ID は、転送を再開したり一時停止したりするために必要な、転送の一意識別子です。

必要に応じて、StartTransferAsync または ResumeTransferAsync に TransferOptions のインスタンスを指定できます。これにより、特定の転送に特定の構成オプションが適用されます。 次の構成オプションを使用できます。

• 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 をコピーする

データ移動ライブラリを使用して、2 つの StorageResource インスタンス間でコピーできます。 BLOB リソースの場合、転送には Put 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 が既に存在する場合にそれを上書きします。 アプリのニーズに応じて 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();

既存の転送を再開する

データ移動ライブラリでは、転送の進行状況をディスクに保持することで、完了前に失敗した転送や、取り消しまたは一時停止された転送を再開できます。 転送を再開するには、持続的なデータから転送を再構築できる StorageResourceProvider インスタンスを使用して TransferManager オブジェクトを構成する必要があります。 プロバイダーを指定するには、TransferManagerOptions クラスの ProvidersForResuming プロパティを使用できます。

次のコード例は、ローカル ファイル システムと Blob Storage 間の転送を再開できる 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 オブジェクトの一部として返される転送の一意識別子です。 転送 ID 値がわからない場合は、TransferManager.GetTransfersAsync を呼び出して、転送とそれに対応する ID を見つけることができます。

次のコード例は、転送を再開する方法を示しています。

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

Note

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 には、次のプロパティがあります。

プロパティ	タイプ	Description
HasCompletedSuccessfully	Boolean	転送に失敗した、またはスキップされた項目なしで正常に完了したかどうかを表します。
HasFailedItems	Boolean	転送に失敗した項目があるかどうかを表します。 true に設定されている場合、転送には少なくとも 1 つの失敗した項目があります。 false に設定されている場合、転送には現状失敗はありません。
HasSkippedItems	Boolean	転送にスキップされた項目があるかどうかを表します。 true に設定されている場合、転送には少なくとも 1 つのスキップされた項目があります。 false に設定されている場合、転送には現状スキップされた項目はありません。 TransferOptions.CreationMode で SkipIfExists が有効になっていない場合、項目がスキップされることはありません。
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 の拡張メソッドを使用する

Azure.Storage.Blobs の BlobContainerClient クラスを使用する既存のコードを持つアプリケーションの場合、拡張メソッドを使用して BlobContainerClient オブジェクトから直接転送を開始できます。 この拡張メソッドは、BlobContainerClientExtensions クラス (または Azure Files の場合は ShareDirectoryClientExtensions) で提供されます。これは、最小限のコード変更で TransferManager を使用する利点の一部を提供します。 このセクションでは、拡張メソッドを使用して BlobContainerClient オブジェクトから転送を実行する方法について説明します。

Azure.Storage.Blobs パッケージがまだインストールされていない場合はインストールします。

dotnet add package Azure.Storage.Blobs

コード ファイルの先頭に次の using ディレクティブを追加します。

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

次のコード例は、sample-container という名前の BLOB コンテナー用の BlobContainerClient をインスタンス化する方法を示しています。

// 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");

次のコード例は、UploadDirectoryAsync を使用してローカル ディレクトリの内容を sample-container にアップロードする方法を示しています。

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

await transfer.WaitForCompletionAsync();

次のコード例は、DownloadToDirectoryAsync を使用して sample-container の内容をローカル ディレクトリにダウンロードする方法を示しています。

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

await transfer.WaitForCompletionAsync();

BlobContainerClient の拡張メソッドの詳細については、「BlobContainerClient の拡張機能」を参照してください。

次のステップ

• DataMovement.Blobs および DataMovement.Files.Shares のコード サンプルは、Azure SDK for .NET GitHub リポジトリで入手できます。