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

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

Клиентскую библиотеку Хранилища BLOB-объектов Azure версии 12 для C++ можно использовать для выполнения таких задач:

  • Создание контейнера
  • передача большого двоичного объекта в хранилище Azure;
  • перечисление всех больших двоичных объектов в контейнере;
  • скачивание большого двоичного объекта на локальный компьютер;
  • Удаление контейнера

Ресурсы:

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

Настройка

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

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

Команда vcpkg install установит пакет SDK Azure Storage Blobs для C++ и необходимые зависимости.

vcpkg.exe install azure-storage-blobs-cpp:x64-windows

Для получения дополнительных сведений посетите сайт GitHub, чтобы получить и создать пакет Azure SDK для C++.

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

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

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

Копирование учетных данных с портала Azure

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

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

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

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

    Screenshot that shows where the access key settings are in the Azure portal

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

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

    Screenshot showing how to copy a connection string from the Azure portal

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

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

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

Перезапуск программ

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

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

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

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

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

Diagram of Blob Storage architecture

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

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

Примеры кода

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

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

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

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

Получение строки подключения

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

Добавьте этот код в 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

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

Создайте экземпляр класса BlobContainerClient, вызвав функцию CreateFromConnectionString. Затем вызовите CreateIfNotExists, чтобы создать контейнер в учетной записи хранения.

Важно!

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

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

using namespace Azure::Storage::Blobs;

std::string containerName = "myblobcontainer";

// Initialize a new instance of BlobContainerClient
BlobContainerClient containerClient
    = BlobContainerClient::CreateFromConnectionString(connectionString, containerName);

// Create the container. This will do nothing if the container already exists.
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 v12 - 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-объектов, перейдите к следующему разделу: