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

Отправка большого двоичного объекта с помощью .NET

  • Статья

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

Необходимые компоненты

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

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

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

В каталоге проекта установите пакеты для клиентских библиотек Хранилище BLOB-объектов Azure и удостоверений Azure с помощью 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 (рекомендуется), требуется встроенный участник данных хранилища BLOB-объектов хранилища ролей или более поздней версии. Дополнительные сведения см. в руководстве по авторизации для Put BLOB-объектов (REST API) и Put Block (REST API).

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

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

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

Чтобы открыть поток в хранилище 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();
}

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

В следующем примере передается блочный большой двоичный объект из строки:

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-объекта с параметрами конфигурации

При отправке большого двоичного объекта можно определить параметры конфигурации клиентской библиотеки. Эти параметры можно настроить для повышения производительности, повышения надежности и оптимизации затрат. В следующих примерах кода показано, как использовать 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:

Имя. Стоимость Описание
Авто 0 Рекомендуется. Позволяет библиотеке выбирать алгоритм. Разные версии библиотеки могут выбирать разные алгоритмы.
нет 1 Нет выбранного алгоритма. Не вычисляйте или не запрашивайте контрольные суммы.
MD5 2 Стандартный хэш-алгоритм MD5.
StorageCrc64 3 служба хранилища Azure 64-разрядной CRC.

Примечание.

Если контрольная сумма, указанная в запросе, не соответствует контрольной сумме, вычисляемой службой, операция отправки завершается ошибкой. Операция не выполняется при использовании политики повторных попыток по умолчанию. В .NET RequestFailedException создается код состояния 400 и код Md5Mismatch ошибки или Crc64Mismatchв зависимости от используемого алгоритма.

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

Теги индекса больших двоичных объектов классифицируют данные в учетной записи хранения с помощью атрибутов тегов типа "ключ-значение". Эти теги автоматически индексируются и представляются в виде многомерного индекса с поддержкой поиска для упрощения нахождения данных. Теги можно добавить в экземпляр 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);
}

Настройка уровня доступа большого двоичного объекта при отправке

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

Ресурсы

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

Примеры кода

Операции REST API

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

См. также

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

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