Краткое руководство. Хранилище BLOB-объектов Azure клиентская библиотека для C++

  • Статья

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

| Примеры исходного кода библиотеки исходного кода | библиотеки API | |

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

Установка

В этом разделе описывается подготовка проекта для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для C++. Самый простой способ получить пакет SDK Azure для C++ — использовать vcpkg диспетчер пакетов.

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

vcpkg install Используйте команду для установки библиотеки Хранилище BLOB-объектов Azure для C++ и необходимых зависимостей:

vcpkg.exe install azure-storage-blobs-cpp

Библиотека удостоверений Azure необходима для бессерверных подключений к службам Azure:

vcpkg.exe install azure-identity-cpp

Дополнительные сведения о настройке проекта и работе с пакетом SDK Azure для C++см. в пакете SDK Azure для C++ readme.

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

В Visual Studio создайте консольное приложение C++ для Windows под названием BlobQuickstart.

Visual Studio dialog for configuring a new C++ Windows console app

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

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

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

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

Diagram of Blob Storage architecture

Используйте эти классы C++ для взаимодействия с данными ресурсами.

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

Примеры кода

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

Добавление включения файлов

Из каталога проекта:

  1. Открытие файла решения BlobQuickstart.sln в Visual Studio
  2. В Visual Studio откройте исходный файл BlobQuickstart.cpp
  3. Удалите весь код в main, который был создан автоматически.
  4. Добавление #include и using namespace операторы
#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

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

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

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

Библиотека удостоверений Azure обеспечивает поддержку проверки подлинности маркера Microsoft Entra в пакете SDK Azure. Он предоставляет набор реализаций TokenCredential , которые можно использовать для создания клиентов пакета SDK Azure, которые поддерживают проверку подлинности маркера Microsoft Entra. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения.

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

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

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

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

Важно!

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

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

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

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

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

    A screenshot showing how to assign a role.

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

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

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

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

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

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

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

    az login

  2. Чтобы использоватьDefaultAzureCredential, убедитесь, что установлен пакет azure-identity-cpp и добавляется следующее#include:

    #include <azure/identity/default_azure_credential.hpp>

  3. Добавьте этот код в конец main(). Когда код выполняется на локальной рабочей станции, DefaultAzureCredential использует учетные данные разработчика для Azure CLI для проверки подлинности в Azure.

    // Initialize an instance of DefaultAzureCredential
 auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();

 auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
 BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);

  4. Обязательно обновите имя учетной записи хранения в URI объекта BlobServiceClient . Имя учетной записи хранения можно найти на странице обзора портала Azure.

    A screenshot showing how to find the storage account name.

    Примечание.

    При использовании пакета SDK C++ в рабочей среде рекомендуется включить только учетные данные, которые вы знаете, что приложение будет использовать. Вместо использования DefaultAzureCredentialследует авторизовать использование определенного типа учетных данных или использовать ChainedTokenCredential с поддерживаемыми учетными данными.

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

Выберите имя нового контейнера. Затем создайте экземпляр BlobContainerClient и создайте контейнер.

Важно!

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

Добавьте этот код в конец main():

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

отправка больших двоичных объектов в контейнер;

Приведенный ниже фрагмент кода:

  1. Объявляет строку, содержащую "Hello Azure!"
  2. Возвращает ссылку на объект BlockBlobClient, вызывая GetBlockBlobClient для контейнера из раздела Создание контейнера.
  3. Передает строку в BLOB-объект, вызывая функцию UploadFrom. С помощью этой функции создается большой двоичный объект, если он не был создан ранее, или же, если он имеется, происходит его обновление.

Добавьте этот код в конец main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

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

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

Добавьте этот код в конец main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

скачивание больших двоичных объектов;

Получите свойства отправленного большого двоичного объекта. Затем объявите новый объект std::vector<uint8_t> и измените его размер, используя свойства отправленного большого двоичного объекта. Скачайте ранее созданный большой двоичный объект в новый std::vector<uint8_t>, вызвав функцию DownloadTo в базовом классе BlobClient. Наконец, отобразите скачанные данные большого двоичного объекта.

Добавьте этот код в конец main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Удаление BLOB-объекта

Следующий код удаляет большой двоичный объект из контейнера Хранилища BLOB-объектов Azure, вызывая функцию BlobClient.Delete.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

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

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

Добавьте этот код в конец main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

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

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

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

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

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

Из этого краткого руководства вы узнали, как передавать, загружать и перечислять файлы в большие двоичные объекты с помощью C++. Кроме того, вы научились создавать и удалять контейнер Хранилища BLOB-объектов Azure.

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

Хранилище BLOB-объектов Azure клиентская библиотека для примеров C++