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

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

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

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

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Компилятор C++.
• CMake.
• vcpkg — диспетчер пакетов C и C++

Установка

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

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

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

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

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

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

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

Примеры кода

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

• Добавление включения файлов
• Проверка подлинности в Azure и авторизация доступа к данным BLOB-объектов
• Создание контейнера
• отправка больших двоичных объектов в контейнер;
• перечисление больших двоичных объектов в контейнере;
• скачивание больших двоичных объектов;
• Удаление контейнера

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

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

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

Портал Azure

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

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

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

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

   

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

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

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

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

Azure CLI

Чтобы назначить роль на уровне ресурсов с помощью Azure CLI, сначала необходимо получить идентификатор ресурса с помощью команды az storage account show. Вы можете отфильтровать выходные свойства с помощью параметра --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Скопируйте выходной Id из предыдущей команды. Затем можно назначить роли с помощью команды az role в Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Чтобы назначить роль на уровне ресурсов с помощью Azure PowerShell, сначала необходимо получить идентификатор ресурса с помощью Get-AzResource команды.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Скопируйте значение Id из выходных данных предыдущей команды. После этого можно назначить роли с помощью команды New-AzRoleAssignment в PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Войдите и подключите код приложения к 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.

   

   Примечание.

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

Строка подключения

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

Примечание.

Чтобы авторизовать доступ к данным с помощью ключа доступа к учетной записи хранения, вам потребуются разрешения для следующих действий Azure RBAC: Microsoft.служба хранилища/storageAccounts/listkeys/action. Наименее привилегированная встроенная роль с разрешениями для этого действия — читатель и доступ к данным, но любая роль, которая включает это действие, будет работать.

Портал Azure

1. Войдите на портал Azure.

2. Перейдите к учетной записи хранения.

3. На панели меню учетной записи хранения в разделе Безопасность и сети выберите Ключи доступа. На этой странице вы увидите ключи доступа к учетной записи и полную строку подключения для каждого ключа.

4. В области Ключи доступа выберите команду Показать ключи.

5. В разделе key1 выберите значение Строка подключения. Нажмите значок Копировать в буфер обмена, чтобы скопировать строку подключения. В следующем разделе вы добавите значение строки подключения в переменную среды.

   

Azure CLI

Строку подключения для своей учетной записи хранения можно просмотреть, выполнив команду az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Вы можете собрать строку подключения с помощью PowerShell, выполнив команды Get-AzStorageAccount и Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Настройка строки подключения хранилища

После копирования строки подключения запишите ее в переменной среды на локальном компьютере, где выполняется приложение. Чтобы задать переменную среды, откройте окно консоли и следуйте инструкциям для используемой операционной системы. Замените <yourconnectionstring> фактической строкой подключения.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

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

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Важно!

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

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

Выберите имя нового контейнера. Затем создайте экземпляр 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++