Поделиться через

Загрузка BLOB с помощью .NET

В этой статье показано, как скачать двоичный объект с использованием клиентской библиотеки Azure Storage для .NET. Данные BLOB можно скачать в разные места, включая локальный файл, поток или текстовую строку. Вы также можете открыть поток BLOB-объектов и прочитать из него.

Предварительные условия

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для .NET. Ниже приведены шаги по установке пакета, добавлению using директив и созданию авторизованного клиентского объекта. Дополнительные сведения см. в статье Начало работы с хранилищем объектов BLOB Azure и .NET.

Установка пакетов

В каталоге вашего проекта установите пакеты клиентских библиотек для Azure Blob Storage и Azure Identity с помощью команды dotnet add package. Пакет Azure.Identity необходим для безпарольных подключений к службам Azure.

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-объектов, создайте экземпляр BLOBServiceClient. В следующем примере показано, как создать клиентский объект с помощью DefaultAzureCredential авторизации:

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

    return client;
}

Вы можете зарегистрировать клиент службы для внедрения зависимостей в приложении .NET.

Вы также можете создавать клиентские объекты для определенных контейнеров или блобов. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

Авторизация

Механизм авторизации должен иметь необходимые разрешения для выполнения операции скачивания. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется) требуется встроенная роль Azure RBAC чтения данных BLOB-хранилища или более высокая. Дополнительные сведения см. в руководстве по авторизации для получения BLOB-объектов (REST API).

Скачивание большого двоичного объекта

Для скачивания большого двоичного объекта можно использовать любой из следующих методов:

Вы также можете открыть поток для чтения из BLOB. Поток загружает большой двоичный объект только по мере чтения потока. Для этого можно использовать один из следующих методов:

Загрузка по пути к файлу

В следующем примере блоб закачивается по локальному пути к файлу. Если указанный каталог не существует, код создает исключение DirectoryNotFoundException. Если файл уже существует по адресу localFilePath, он будет перезаписан по умолчанию во время последующих загрузок.

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

Скачивание в поток

В следующем примере большой двоичный объект скачивается путем создания объекта Stream, а затем загружается в этот поток. Если указанный каталог не существует, код создает исключение 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();
}

Скачивание из потока

В следующем примере блоб скачивается путем чтения из потока.

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-объекта с настройками

При скачивании большого двоичного объекта можно определить параметры конфигурации клиентской библиотеки. Эти параметры можно настроить для повышения производительности и повышения надежности. В следующих примерах кода показано, как использовать 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 Рекомендуется. Позволяет библиотеке выбирать алгоритм. Разные версии библиотеки могут выбирать разные алгоритмы.
нет 1 Нет выбранного алгоритма. Не вычисляйте или не запрашивайте контрольные суммы.
MD5 2 Стандартный хэш-алгоритм MD5.
StorageCrc64 3 Пользовательская 64-битная контрольная сумма CRC для Azure Storage.

Ресурсы

Дополнительную информацию о том, как загрузить BLOB-объекты с помощью клиентской библиотеки Azure Blob Storage для .NET, см. в следующих ресурсах.

Примеры кода

Операции REST API

Пакет SDK Azure для .NET содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы .NET. Методы клиентской библиотеки для скачивания больших двоичных объектов используют следующую операцию REST API:

Ресурсы клиентской библиотеки

См. также

Связанный контент

  • Эта статья является частью руководства разработчика хранилища BLOB-объектов для .NET. Дополнительные сведения см. в полном списке статей руководства разработчика по созданию приложения .NET.