Краткое руководство. Использование библиотеки Хранилища BLOB-объектов Azure для .NET

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

Справочная документация по API | исходный код библиотеки | пакет (NuGet) | примеры

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

Настройка

В этом разделе рассматривается подготовка проекта для работы с клиентской библиотекой хранилища BLOB-объектов Azure для .NET.

Создание проекта

Для дальнейших действий необходимо создать консольное приложение .NET, используя интерфейс командной строки .NET или Visual Studio 2022.

  1. В верхней части Visual Studio перейдите к разделу Файл>Новый>Проект...

  2. В диалоговом окне введите в поле поиска шаблона проекта консольное приложение и выберите первый результат. Нажмите Далее в нижней части диалогового окна.

    Снимок экрана, на котором продемонстрировано создание проекта с помощью Visual Studio.

  3. В поле Имя проекта введите BlobQuickstart. Оставьте в остальных полях значения по умолчанию и выберите Далее.

  4. Убедитесь, что в поле Платформа выбрано .NET 6.0. Затем нажмите Создать. Новый проект откроется в среде Visual Studio.

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

Чтобы взаимодействовать с Хранилищем BLOB-объектов Azure, установите клиентскую библиотеку Хранилища BLOB-объектов Azure для .NET.

  1. В Обозревателе решений щелкните правой кнопкой мыши узел зависимостей проекта. Выберите Manage NuGet Packages... (Управление пакетами NuGet...).

  2. В окне, которое откроется, найдите Azure.Storage.Blobs. Выберите соответствующий результат и нажмите Установить.

    Снимок экрана, на котором продемонстрировано добавление пакета с помощью Visual Studio.

Настройка кода приложения

Замените начальный код в файле Program.cs таким образом, чтобы он соответствовал следующему примеру, который включает необходимые инструкции using для этого упражнения.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Проверка подлинности в Azure и авторизация доступа к данным BLOB-объектов

Запросы приложений к Хранилищу BLOB-объектов Azure должны быть авторизованы. Использование класса, предоставленного DefaultAzureCredential клиентской библиотекой удостоверений Azure, является рекомендуемым подходом для реализации подключений без пароля к службам Azure в коде, включая Хранилище BLOB-объектов.

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

DefaultAzureCredential — это класс, предоставляемый клиентской библиотекой удостоверений Azure для .NET. Дополнительные сведения см. в обзоре DefaultAzureCredential. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

Порядок и расположения, в которых DefaultAzureCredential выполняет поиск учетных данных, можно найти в обзоре библиотеки удостоверений Azure.

Например, приложение может пройти проверку подлинности, используя учетные данные для входа в Visual Studio во время локальной разработки. После развертывания приложения в Azure приложение может использовать управляемое удостоверение. Для такого перехода не требуется изменять код.

Назначение ролей учетной записи пользователя Azure AD

Если вы выполняете разработку локально, убедитесь, что учетная запись пользователя, через которую осуществляется доступ к данным BLOB-объектов, имеет правильные разрешения. Вам потребуется участник данных BLOB-объектов хранилища для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, необходимо назначить роль администратора доступа пользователей или другую роль, включающую Майкрософт. Авторизация, рольНазначение и запись действия. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. С дополнительными сведениями о доступных областях назначения ролей можно ознакомиться на странице обзора области.

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

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

Важно!

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

  1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

  2. На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.

  3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

  4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

    Снимок экрана, на котором продемонстрировано назначение роли.

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

  6. В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.

  7. В диалоговом окне найдите имя пользователя Azure AD (обычно ваш адрес электронной почты пользователь@домен), а затем нажмите кнопку Выбрать в нижней части диалогового окна.

  8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Вход и подключение кода приложения к Azure с помощью DefaultAzureCredential

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

  1. Убедитесь, что вы прошли проверку подлинности с помощью той же учетной записи Azure AD, для которую вы назначили роль. Вы можете пройти проверку подлинности с помощью Azure CLI, Visual Studio или Azure PowerShell.

    Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

    az login
    
  2. Чтобы использовать DefaultAzureCredential, добавьте в приложение пакет Azure.Identity.

    1. В Обозревателе решений щелкните правой кнопкой мыши узел зависимостей проекта. Выберите Manage NuGet Packages... (Управление пакетами NuGet...).

    2. В окне, которое откроется, найдите Azure.Identity. Выберите соответствующий результат и нажмите Установить.

      Снимок экрана, на котором показано добавление пакета удостоверений.

  3. Обновите код Program.cs, чтобы он соответствовал следующему примеру. Когда код выполняется на локальной рабочей станции во время разработки, он будет использовать учетные данные разработчика для приоритетных инструментов, в которые вы вошли для прохождения проверки подлинности в Azure, например Azure CLI или Visual Studio.

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using Azure.Identity;
    
    // TODO: Replace <storage-account-name> with your actual storage account name
    var blobServiceClient = new BlobServiceClient(
            new Uri("https://<storage-account-name>.blob.core.windows.net"),
            new DefaultAzureCredential());
    
  4. Обязательно обновите имя учетной записи хранения в универсальном коде ресурса (URI) своего BlobServiceClient. Имя учетной записи хранения можно найти на странице обзора портала Azure.

    Снимок экрана: как найти имя учетной записи хранения.

    Примечание

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

Объектная модель

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

  • учетная запись хранения;
  • контейнер в учетной записи хранения;
  • большой двоичный объект в контейнере.

На следующей схеме показана связь между этими ресурсами.

Схема архитектуры Хранилища BLOB-объектов.

Используйте следующие классы .NET для взаимодействия с этими ресурсами:

  • BlobServiceClient. Класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами больших двоичных объектов.
  • BlobContainerClient. Класс BlobContainerClient позволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.
  • BlobClient. Класс BlobClient позволяет управлять большими двоичными объектами службы хранилища Azure.

Примеры кода

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

Важно!

Убедитесь, что установлены правильные пакеты NuGet и добавлены необходимые операторы using, чтобы примеры кода работали в соответствии с описанием раздела с настройкой.

  • Azure.Identity (если вы используете подход без пароля)
  • Azure.Storage.Blobs

Создание контейнера

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

Важно!

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

Вы можете вызвать метод CreateBlobContainerAsync в blobServiceClient, чтобы создать контейнер в своей учетной записи хранения.

Добавьте в конец класса Program.cs следующий код:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Отправка большого двоичного объекта в контейнер

Добавьте в конец класса Program.cs следующий код:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Фрагмент кода выполняет следующие действия:

  1. Создает текстовый файл в локальном каталоге data.
  2. Возвращает ссылку на объект BlobClient, вызывая метод GetBlobClient для контейнера из раздела Создание контейнера.
  3. Передает локальный текстовый файл в большой двоичный объект, вызывая метод UploadAsync. С помощью этого метода создается большой двоичный объект, если он не был создан ранее, или же, если он имеется, происходит его замещение.

Получение списка BLOB-объектов в контейнере

Выведите список больших двоичных объектов в контейнере, вызвав метод GetBlobsAsync. В этом случае в контейнер был добавлен лишь один большой двоичный объект, поэтому операция перечисления возвращает только его.

Добавьте в конец класса Program.cs следующий код:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Загрузка больших двоичных объектов

Скачайте созданный ранее BLOB-объект, вызвав метод DownloadToAsync. Пример кода добавляет суффикс "DOWNLOADED" к имени файла, чтобы в локальной файловой системе можно было просмотреть оба файла.

Добавьте в конец класса Program.cs следующий код:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Удаление контейнера

Следующий код очищает созданные приложением ресурсы, полностью удаляя контейнер с помощью метода DeleteAsync. Он также удаляет локальные файлы, созданные приложением.

Приложение приостанавливается для ввода пользователя, вызывая Console.ReadLine, перед удалением большого двоичного объекта, контейнера и локальных файлов. Это хорошая возможность проверить правильность создания ресурсов перед их удалением.

Добавьте в конец класса Program.cs следующий код:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Полный код

После выполнения этих действий код в файле Program.cs должен выглядеть следующим образом:

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

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Выполнение кода

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

Если вы используете Visual Studio, нажмите клавишу F5, чтобы создать и запустить код и взаимодействовать с консольным приложением. Если вы используете интерфейс командной строки .NET, перейдите к каталогу приложения, выполните его сборку и запустите это приложение.

dotnet build
dotnet run

Вы должны увидеть выходные данные приложения, как показано ниже.

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Прежде чем начать удаление, проверьте наличие двух файлов в папке data. Вы можете открыть их и убедиться, что они идентичны.

После проверки файлов нажмите клавишу ВВОД, чтобы завершить работу с демонстрационной версией и удалить тестовые файлы.

Дальнейшие действия

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

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