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

Быстрый старт: клиентская библиотека Хранилища Blob-объектов Azure для .NET

  • Статья

Примечание.

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

Примечание.

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

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

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

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

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

В этом видео показано, как начать использовать клиентскую библиотеку Azure Blob Storage для .NET.

Действия в видео также описаны в следующих разделах.

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

Установка

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

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

Создайте консольное приложение .NET с помощью .NET CLI или Visual Studio 2022.

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

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

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

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

  4. Для платформы убедитесь, что выбрана последняя установленная версия .NET. Щелкните Создать. Новый проект открывается в среде 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 можно создать учетную запись хранения и запустить пример кода с помощью нескольких команд. Проект можно запустить в локальной среде разработки или в DevContainer.

Инициализация шаблона интерфейса командной строки разработчика Azure и развертывание ресурсов

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

  • Клонируйте ресурсы репозитория квикстарт из GitHub и инициализируйте шаблон на локальной машине.

    azd init --template blob-storage-quickstart-dotnet

    Вам будет предложено получить следующие сведения:

    • Имя среды: это значение используется в качестве префикса для всех ресурсов Azure, созданных Azure Developer CLI. Имя должно быть уникальным для всех подписок Azure и должно составлять от 3 до 24 символов. Имя может содержать только цифры и строчные буквы.

  • Войдите в Azure:

    azd auth login

  • Подготовка и развертывание ресурсов в Azure:

    azd up

    Вам будет предложено получить следующие сведения:

    • Подписка: подписка Azure, в которую развертываются ваши ресурсы.
    • Расположение: регион Azure, в котором развернуты ресурсы.

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

Запуск примера кода

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

  • Обновите имя учетной записи хранения: перейдите к каталогу src и измените его Program.cs. Найдите заполнитель <storage-account-name> и замените его на фактическое имя учетной записи хранения, созданное командой azd up. Сохраните изменения.
  • Запустите проект: если вы используете Visual Studio, нажмите клавишу F5, чтобы создать и запустить код и взаимодействовать с консольным приложением. Если вы используете интерфейс командной строки .NET, перейдите в каталог приложения, создайте проект с помощью dotnet buildи запустите приложение с помощью dotnet run.
  • Просмотрите выходные данные: это приложение создает тестовый файл в локальной папке данных и отправляет его в контейнер в учетной записи хранения. Затем в контейнере выводится список объектов BLOB, и файл загружается с новым именем, чтобы можно было сравнить старую и новую версии файлов.

Чтобы узнать больше о том, как работает пример кода, смотрите Примеры кода.

После завершения тестирования кода см. раздел "Очистка ресурсов", чтобы удалить ресурсы, созданные командой azd up.

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

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

  • учетная запись хранения;
  • контейнер в аккаунте хранилища
  • BLOB в контейнере.

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

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

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

  • BlobServiceClient: класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами BLOB-объектов.
  • BlobContainerClient: класс BlobContainerClient позволяет управлять контейнерами Azure Storage и их блобами.
  • BlobClient: класс BlobClient позволяет управлять BLOB-объектами службы хранилища Azure.

Примеры кода

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

Внимание

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

Примечание.

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

Аутентификация в Azure и авторизация доступа к объектам BLOB

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

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

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

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

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

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

Если вы выполняете разработку локально, убедитесь, что учетная запись пользователя, через которую осуществляется доступ к данным BLOB-объектов, имеет правильные разрешения. Вам потребуется роль Storage Blob Data Contributor для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, вам потребуется, чтобы вам назначили роль администратора доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о доступных областях назначения ролей можно узнать на странице обзора области.

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

  1. Для локальной разработки убедитесь, что вы авторизованы с той же учетной записью Microsoft Entra, которую вы назначили для роли. Вы можете пройти проверку подлинности с помощью популярных средств разработки, таких как Azure CLI или 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.

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

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

Добавьте следующий код в конец файла 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);

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

Внимание

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

Загрузка объекта типа BLOB в контейнер

Отправьте блок данных в контейнер с помощью UploadAsync. Пример кода создает текстовый файл в локальном каталоге данных для отправки в контейнер.

Добавьте следующий код в конец файла 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, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Дополнительные сведения о отправке больших двоичных объектов и изучении дополнительных примеров кода см. в статье "Отправка большого двоичного объекта с помощью .NET".

Перечень объектов в контейнере

Получите список объектов 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);
}

Дополнительные сведения о перечислении больших двоичных объектов и дополнительные примеры кода см. в статье "Список больших двоичных объектов" с помощью .NET.

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

Скачайте созданный ранее большой двоичный объект, вызвав метод 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);

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

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

Следующий код очищает ресурсы, созданные приложением, удалив контейнер с помощью 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");

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

Полный код

После выполнения этих действий код в 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

Выходные данные приложения аналогичны следующему примеру (значения GUID, пропущенные для удобочитаемости):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

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

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

Очистка ресурсов

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

Когда вы завершите быстрое начало, вы можете очистить созданные ресурсы, выполнив следующую команду:

azd down

Вам будет предложено подтвердить удаление ресурсов. Введите y для подтверждения.

Следующий шаг

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