.NET 用 Azure Storage データ移動 BLOB クライアントライブラリ - バージョン 12.0.0-beta.3

[アーティクル]
07/12/2023

サーバーバージョン: 2020-04-08、2020-02-10、2019-12-12、2019-07-07、および 2020-02-02

Azure Storage は、高い可用性とセキュリティ、耐久性、スケーラビリティ、冗長性を備えたクラウドストレージを提供する、Microsoft が管理するクラウドサービスです。 Azure Storage には、Azure BLOB (オブジェクト)、Azure Data Lake Storage Gen2、Azure Files、Azure キューが含まれます。

Azure Storage データ移動ライブラリは、顧客データのアップロード、ダウンロード、コピー用に最適化されています。

Azure.Storage.DataMovement.Blobs ライブラリは、他の Azure Storage クライアントライブラリによって共有されるインフラストラクチャを提供します。

ソースコード | パッケージ (NuGet) | API リファレンスドキュメント | REST API のドキュメント | 製品ドキュメント

作業の開始

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

NuGet で使用する .NET 用 Azure Storage クライアントライブラリをインストールすると、Azure.Storage.DataMovement.Blobsクライアントライブラリが含まれます。

dotnet add package Azure.Storage.DataMovement --prerelease
dotnet add package Azure.Storage.DataMovement.Blobs --prerelease

前提条件

このパッケージを使用するには、 Azure サブスクリプションとストレージアカウントが必要です。

新しいストレージアカウントを作成するには、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。 Azure CLI を使う例を次に示します。

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

クライアントを認証する

Azure.Storage.DataMovement.Blobs ライブラリは、Azure.Storage.Blobs パッケージのクライアントを使用して、Azure Blob Storage サービスと通信します。詳細については、Azure.Storage.Blobs 認証に関するドキュメントを参照してください。

主要な概念

Azure Storage Common クライアントライブラリには、[認証資格情報][auth_credentials] や RequestFailedException などの共有インフラストラクチャが含まれています。

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、クライアントインスタンスの再利用に関する推奨事項は、スレッド間でも常に安全になります。

その他の概念

例

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

BlobContainerClient をインスタンス化する

BlobServiceClient service = new BlobServiceClient(serviceUri, credential);

BlobContainerClient container = service.GetBlobContainerClient(containerName);

コンテナーのルートにローカルディレクトリをアップロードする

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath);

await transfer.AwaitCompletion();

ディレクトリプレフィックスを指定して、コンテナー内の仮想ディレクトリにローカルディレクトリをアップロードする

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath, blobDirectoryPrefix);

await transfer.AwaitCompletion();

より高度なオプションを指定して、コンテナー内の仮想ディレクトリにローカルディレクトリをアップロードする

BlobContainerClientTransferOptions options = new BlobContainerClientTransferOptions
{
    BlobContainerOptions = new BlobStorageResourceContainerOptions
    {
        DirectoryPrefix = blobDirectoryPrefix
    },
    TransferOptions = new TransferOptions()
    {
        CreateMode = StorageResourceCreateMode.Overwrite,
    }
};

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath, options);

await transfer.AwaitCompletion();

コンテナー全体をローカルディレクトリにダウンロードする

DataTransfer transfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath);

await transfer.AwaitCompletion();

ディレクトリプレフィックスを指定してコンテナー内のディレクトリをダウンロードする

DataTransfer tranfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath2, blobDirectoryPrefix);

await tranfer.AwaitCompletion();

より高度なオプションを指定してコンテナーからダウンロードする

BlobContainerClientTransferOptions options = new BlobContainerClientTransferOptions
{
    BlobContainerOptions = new BlobStorageResourceContainerOptions
    {
        DirectoryPrefix = blobDirectoryPrefix
    },
    TransferOptions = new TransferOptions()
    {
        CreateMode = StorageResourceCreateMode.Overwrite,
    }
};

DataTransfer tranfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath2, options);

await tranfer.AwaitCompletion();

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

オプションを使用して TransferManager のインスタンスを作成する

// Create BlobTransferManager with event handler in Options bag
TransferManagerOptions transferManagerOptions = new TransferManagerOptions();
TransferOptions options = new TransferOptions()
{
    MaximumTransferChunkSize = 4 * Constants.MB,
    CreateMode = StorageResourceCreateMode.Overwrite,
};
TransferManager transferManager = new TransferManager(transferManagerOptions);

ローカルファイルからブロック BLOB へのアップロードを開始する

DataTransfer dataTransfer = await transferManager.StartTransferAsync(
    sourceResource: new LocalFileStorageResource(sourceLocalPath),
    destinationResource: new BlockBlobStorageResource(destinationBlob));
await dataTransfer.AwaitCompletion();

ブロック BLOB ダウンロードにオプションを適用する

await transferManager.StartTransferAsync(
    sourceResource: new BlockBlobStorageResource(sourceBlob, new BlockBlobStorageResourceOptions()
    {
        DestinationConditions = new BlobRequestConditions(){ LeaseId = "xyz" }
    }),
    destinationResource: new LocalFileStorageResource(downloadPath2));

ディレクトリのアップロードを開始する

// Create simple transfer directory upload job which uploads the directory and the contents of that directory
DataTransfer dataTransfer = await transferManager.StartTransferAsync(
    sourceResource: new LocalDirectoryStorageResourceContainer(sourcePath),
    destinationResource: new BlobStorageResourceContainer(
        container,
        new BlobStorageResourceContainerOptions() { DirectoryPrefix = "sample-directory2" }),
    transferOptions: options);

ディレクトリのダウンロードを開始する

DataTransfer downloadDirectoryJobId2 = await transferManager.StartTransferAsync(
    sourceDirectory2,
    destinationDirectory2);

転送マネージャーオプションの簡単なロガーサンプル

// Create BlobTransferManager with event handler in Options bag
TransferManagerOptions options = new TransferManagerOptions();
TransferOptions transferOptions = new TransferOptions();
transferOptions.SingleTransferCompleted += (SingleTransferCompletedEventArgs args) =>
{
    using (StreamWriter logStream = File.AppendText(logFile))
    {
        logStream.WriteLine($"File Completed Transfer: {args.SourceResource.Path}");
    }
    return Task.CompletedTask;
};

コンテナー転送オプションの単純な失敗したイベント委任

transferOptions.TransferFailed += (TransferFailedEventArgs args) =>
{
    using (StreamWriter logStream = File.AppendText(logFile))
    {
        // Specifying specific resources that failed, since its a directory transfer
        // maybe only one file failed out of many
        logStream.WriteLine($"Exception occured with TransferId: {args.TransferId}," +
            $"Source Resource: {args.SourceResource.Path}, +" +
            $"Destination Resource: {args.DestinationResource.Path}," +
            $"Exception Message: {args.Exception.Message}");
    }
    return Task.CompletedTask;
};

トラブルシューティング

すべての Azure Storage サービスは、役に立つと共に RequestFailedException をスローします。ErrorCode

次のステップ

Blob DataMovement サンプルの概要。

共同作成

これらのライブラリの構築、テスト、および貢献の詳細については、「 Storage CONTRIBUTING.md 」を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

.NET 用 Azure Storage データ移動 BLOB クライアントライブラリ - バージョン 12.0.0-beta.3

作業の開始

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

前提条件

クライアントを認証する

主要な概念

スレッドセーフ

その他の概念

例

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

次の方法で共有

.NET 用 Azure Storage データ移動 BLOB クライアント ライブラリ - バージョン 12.0.0-beta.3

作業の開始

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

前提条件

クライアントを認証する

主要な概念

スレッド セーフ

その他の概念

例

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

BlobContainerClient 拡張メソッドを使用してディレクトリをアップロードおよびダウンロードする例。

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

.NET 用 Azure Storage データ移動 BLOB クライアントライブラリ - バージョン 12.0.0-beta.3

スレッドセーフ