Загрузить блоб с помощью .NET

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

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

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Последняя версия .NET SDK для вашей операционной системы. Обязательно получите пакет SDK, а не среду выполнения.

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

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище 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.

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

Авторизация

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

Отправка данных в блочный BLOB-объект

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

• Отправить
• UploadAsync

При использовании этих методов отправки клиентская библиотека может вызывать либо Put Blob, либо ряд Put Block вызовов, за которыми следует Put Block List. Это поведение зависит от общего размера объекта и способа установки параметров передачи данных.

Чтобы открыть поток в хранилище BLOB-объектов и записать его в этот поток, используйте любой из следующих методов:

• OpenWrite
• OpenWriteAsync

Загрузить блочный BLOB-объект из локального пути к файлу

В следующем примере загружается блочный BLOB из локального пути к файлу:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Отправка блочного BLOB-объекта из потока

В следующем примере загружается блочный BLOB-объект путем создания объекта Stream и загрузки потока.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Отправка блочного BLOB-объекта из объекта BinaryData

В следующем примере загружается блочный двоичный объект из объект BinaryData.

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Загрузка блоб-объекта из строки

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

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Отправка в поток в Хранилище BLOB-объектов

Вы можете открыть поток в хранилище BLOB-объектов и записать в него. В следующем примере создается ZIP-файл в Blob-хранилище и записывают в него файлы. Вместо создания ZIP-файла в локальной памяти, в память одновременно помещается лишь один файл.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Отправка блочного BLOB-объекта с параметрами конфигурации

При загрузке объекта BLOB можно задать параметры конфигурации клиентской библиотеки. Эти параметры можно настроить для повышения производительности, повышения надежности и оптимизации затрат. В следующих примерах кода показано, как использовать BLOBUploadOptions для определения параметров конфигурации при вызове метода отправки.

Указание параметров передачи данных при отправке

Значения в StorageTransferOptions можно настроить для повышения производительности операций передачи данных. В следующем примере кода показано, как задать значения для StorageTransferOptions и включить параметры в составе экземпляра BlobUploadOptions. Значения, указанные в этом примере, не предназначены для рекомендации. Чтобы правильно настроить эти значения, необходимо учитывать конкретные потребности приложения.

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    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
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Дополнительные сведения о настройке параметров передачи данных см. в разделе "Настройка производительности" для отправки и скачивания с помощью .NET.

Укажите параметры проверки передачи при загрузке

Вы можете указать параметры проверки передачи, чтобы убедиться, что данные загружаются правильно и не были изменены во время передачи. Параметры проверки передачи можно определить на уровне клиента с помощью BlobClientOptions, который применяет параметры проверки ко всем методам, вызываемым из экземпляра BLOBClient .

Можно также переопределить параметры проверки передачи на уровне метода с помощью BLOBUploadOptions. В следующем примере кода показано, как создать BlobUploadOptions объект и указать алгоритм создания контрольной суммы. Затем контрольная сумма используется службой для проверки целостности данных отправленного содержимого.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

В следующей таблице показаны доступные параметры алгоритма контрольной суммы, как определено StorageChecksumAlgorithm:

Отправка с помощью тегов индекса

Теги индекса Blob категоризируют данные в вашей учетной записи хранения с помощью атрибутов тегов "ключ-значение". Эти теги автоматически индексируются и представляются в виде многомерного индекса с поддержкой поиска для упрощения нахождения данных. Вы можете добавить теги в экземпляр BlobUploadOptions и передать его в метод UploadAsync.

В следующем примере загружается блочный BLOB с тегами индекса:

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Установка уровня доступа объекта BLOB при загрузке

Уровень доступа большого двоичного объекта можно задать при загрузке с использованием класса BlobUploadOptions. В следующем примере кода показано, как задать уровень доступа при загрузке большого двоичного объекта.

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Установка уровня доступа разрешена только для блочных блобов. Вы можете установить уровень доступа для блочного blob на Hot, Cool, Cold или Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.15.0.

Дополнительные сведения о уровнях доступа см. в обзоре уровней доступа.

Загрузить блочный BLOB путем поэтапной загрузки и фиксации блоков

Вы можете получить больший контроль над разделением загрузок на блоки путем ручной организации отдельных блоков данных. Когда все блоки, составляющие бинарный объект, будут подготовлены, вы сможете зафиксировать их в Блочном хранилище. Этот подход можно использовать для повышения производительности, отправляя блоки параллельно.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Ресурсы

Чтобы узнать больше о загрузке блобов с помощью клиентской библиотеки Azure Blob Storage для .NET, см. следующие ресурсы.

Примеры кода

• Просмотр примеров кода из этой статьи (GitHub)

Операции REST API

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

• Вставка большого двоичного объекта (REST API)
• Put Block (REST API)

См. также

• Настройка производительности для отправки и скачивания.
• Управление данными больших двоичных объектов Azure и их поиск с помощью тегов индекса больших двоичных объектов
• Использование тегов индекса BLOB-объектов для управления и поиска данных на Хранилище BLOB-объектов Azure

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

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