.NET を使用して BLOB をダウンロードする

  • [アーティクル]

この記事では、.NET 用の Azure Storage クライアント ライブラリを使用して BLOB をダウンロードする方法について説明します。 BLOB データは、ローカル ファイル パス、ストリーム、テキスト文字列など、さまざまな宛先にダウンロードできます。 BLOB ストリームを開き、そこから読み取ることもできます。

前提条件

環境を設定する

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

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

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

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

using ディレクティブを追加します

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

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

この記事の一部のコード例では、追加のusing ディレクティブが必要な場合があります。

クライアント オブジェクトの作成

アプリを Blob Storage に接続するには、 BlobServiceClientのインスタンスを作成します。 次の例では、認可のために DefaultAzureCredential を使用してクライアント オブジェクトを作成する方法を示します。

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

.NET アプリに依存関係の挿入用のサービス クライアントを登録できます。

また、特定のコンテナーまたは BLOB 用のクライアント オブジェクトを作成することもできます。 クライアント オブジェクトの作成と管理の詳細については、「データ リソースを操作するクライアント オブジェクトを作成および管理する」を参照してください。

承認

認可メカニズムには、ダウンロード操作を実行するために必要なアクセス許可が必要です。 Microsoft Entra ID を使用した認可 (推奨) には、Azure RBAC 組み込みロールの Storage BLOB データ閲覧者以上が必要です。 詳細については、Get Blob (REST API) に関するページの認可のガイダンスを参照してください。

BLOB をダウンロードする

次のいずれかのメソッドを使用して BLOB をダウンロードできます。

ストリームを開いて BLOB から読み取ることも可能です。 ストリームは、読み取り元とする BLOB のみをダウンロードします。 次のいずれかの方法を使用できます。

ファイル パスへのダウンロード

次の例では、BLOB をローカル ファイル パスにダウンロードします。 指定したディレクトリが存在しない場合は、コードで DirectoryNotFoundException がスローされます。 ファイルが既に localFilePath に存在する場合は、以降のダウンロード時に既定で上書きされます。

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

ストリームへのダウンロード

次の例では、 Stream オブジェクトを作成し、そのストリームにダウンロードすることによって、BLOB をダウンロードします。 指定したディレクトリが存在しない場合は、コードで DirectoryNotFoundException がスローされます。

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

文字列へのダウンロード

次の例では、BLOB がテキスト ファイルであると想定し、BLOB を文字列にダウンロードします。

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

ストリームからのダウンロード

次の例では、ストリームから読み取って BLOB をダウンロードします。

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

構成オプションを使用したブロック BLOB のダウンロード

BLOB をダウンロードするときに、クライアント ライブラリの構成オプションを定義できます。 これらのオプションは、パフォーマンスを向上させたり信頼性を高めたりするために調整できます。 次のコード例は、ダウンロード メソッドを呼び出すときに BlobDownloadToOptions を使用して構成オプションを定義する方法を示しています。 BlobDownloadOptions でも同じオプションを使用できます。

ダウンロード時のデータ転送オプションの指定

StorageTransferOptions で値を構成し、データ転送操作のパフォーマンスを向上させることができます。 次のコード例は、StorageTransferOptions の値を設定し、オプションを BlobDownloadToOptions インスタンスの一部として含める方法を示しています。 このサンプルで提供される値は、推奨を意図したものではありません。 これらの値を適切にチューニングするには、アプリの特定のニーズを考慮する必要があります。

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

データ転送オプションのチューニングの詳細については、アップロードとダウンロードのパフォーマンス チューニングに関するページを参照してください。

ダウンロード時の転送検証オプションの指定

データが正しくダウンロードされて転送中に改ざんされていないことを確認する助けとなるように、転送検証オプションを指定できます。 転送検証オプションは、BlobClientOptions を使用してクライアント レベルで定義できます。これにより、BlobClient インスタンスから呼び出されるすべてのメソッドに検証オプションが適用されます。

BlobDownloadToOptions を使用して、メソッド レベルで転送検証オプションをオーバーライドすることもできます。 次のコード例は、BlobDownloadToOptions オブジェクトを作成し、チェックサムを生成するためのアルゴリズムを指定する方法を示しています。 チェックサムはその後、ダウンロードしたコンテンツのデータ整合性を検証するためにサービスによって使用されます。

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

次の表は、StorageChecksumAlgorithm で定義されている、チェックサム アルゴリズムの使用できるオプションを示しています。

名前 値 説明
自動 0 推奨。 ライブラリでアルゴリズムを選択できるようにします。 ライブラリのバージョンが異なると異なるアルゴリズムが選択される可能性があります。
None 1 アルゴリズムは選択されていません。 チェックサムの計算や要求は行われません。
MD5 2 標準 MD5 ハッシュ アルゴリズム。
StorageCrc64 3 Azure Storage のカスタム 64 ビット CRC。

リソース

.NET 用 Azure Blob Storage クライアント ライブラリを使用して BLOB をダウンロードする方法について詳しくは、次のリソースを参照してください。

コード サンプル

REST API の操作

Azure SDK for .NET には Azure REST API に基づいて構築されたライブラリが含まれるため、使い慣れた .NET パラダイムを通じて REST API 操作を利用できます。 BLOB をダウンロードするためのクライアント ライブラリ メソッドは、次の REST API 操作を使用します。

クライアント ライブラリのリソース

こちらもご覧ください

関連するコンテンツ

  • この記事は、.NET の Blob Storage 開発者ガイドの一部です。 詳細については、「.NET アプリのビルド」にある開発者ガイドの記事の完全な一覧を参照してください。