Использование хранилища очередей из C++
Совет
Пробное использование обозревателя хранилищ Microsoft Azure
Обозреватель хранилищ Microsoft Azure — это бесплатное автономное приложение от корпорации Майкрософт, позволяющее визуализировать данные из службы хранилища Azure на платформе Windows, macOS и Linux.
Обзор
В этом руководстве показано, как реализовать типичные сценарии с использованием службы хранения очередей Azure. Примеры написаны на C++ и используют клиентскую библиотеку хранилища Azure для C++. Здесь описаны такие сценарии, как вставка, просмотр, получение и удаление сообщений очереди, а также создание и удаление очередей.
Примечание
Данное руководство предназначено для клиентской библиотеки хранилища Azure для С++ версии 1.0.0 и выше. Рекомендуемая версия клиентской библиотеки хранилища Azure — 2.2.0. Она доступна на сайте NuGet или GitHub.
Что такое хранилище очередей?
Хранилище очередей Azure — это служба для хранения большого количества сообщений, к которым можно получить доступ практически из любой точки мира с помощью вызовов с проверкой подлинности по протоколам HTTP или HTTPS. Одно сообщение очереди может быть размером до 64 КБ, а очередь может содержать миллионы сообщений до общего ограничения емкости учетной записи хранения. Хранилище очередей часто используется для создания списка невыполненных заданий для асинхронной обработки.
Основные понятия службы очередей
Служба очередей Azure содержит следующие компоненты:
Учетная запись хранения. Весь доступ к хранилищу Azure осуществляется с помощью учетной записи хранения. См. сведения об учетных записях хранения.
Очередь. Очередь содержит набор сообщений. Все сообщения должны находиться в очереди. Обратите внимание: имя очереди должно содержать только строчные символы. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.
Сообщение. Сообщение в любом формате размером до 64 КБ. Сообщение может оставаться в очереди не более 7 дней. Начиная с версии 2017-07-29, максимальный срок жизни может быть задан любым положительным числом или значением -1, свидетельствующим о том, что срок жизни сообщения неограничен. Если этот параметр не указан, срок жизни по умолчанию составляет семь дней.
Формат URL-адреса: обращаться к очередям можно с помощью URL-адреса следующего вида: http://
<storage account>.queue.core.windows.net/<queue>Следующий URL-адрес позволяет обратиться к очереди на схеме:
http://myaccount.queue.core.windows.net/incoming-orders
Создание учетной записи хранения Azure
Самый простой способ создать первую учетную запись хранения Azure — воспользоваться порталом Azure. Дополнительную информацию см. в статье Об учетных записях хранения Azure.
Кроме того, создать учетную запись хранения Azure можно с помощью Azure PowerShell, Azure CLI или поставщика ресурсов службы хранилища Azure для .NET.
Если вы не хотите сейчас создавать учетную запись хранения в Azure, код можно запустить и протестировать в локальной среде с помощью эмулятора хранилища Azurite. Дополнительные сведения см. в статье Использование эмулятора Azurite для разработки и тестирования службы хранилища Azure.
Создание приложения на C++
В этом руководстве будут использоваться компоненты хранилища, которые могут выполняться в приложениях C++.
Для этого необходимо установить клиентскую библиотеку хранилища Azure для C++ и создать учетную запись хранения Azure в подписке Azure.
Установить клиентскую библиотеку хранилища для C++ можно описанными ниже методами.
- Linux: следуйте инструкциям, указанным в файле README клиентской библиотеки хранилища Azure для C++ на странице для начала работы в Linux.
- Windows: В Windows в качестве диспетчера зависимостей используйте vcpkg. Следуйте инструкциям из этого краткого руководства, чтобы инициализировать
vcpkg. Затем, чтобы установить библиотеку, используйте следующую команду:
.\vcpkg.exe install azure-storage-cpp
Руководство по созданию исходного кода и экспорту в Nuget можно просмотреть в файле README.
Настройка приложения для доступа к хранилищу очередей
Если нужно использовать API-интерфейсы Azure для доступа к очередям, добавьте следующие инструкции импорта в верхнюю часть файла C++:
#include <was/storage_account.h>
#include <was/queue.h>
Настройка строки подключения к службе хранилища Azure
Клиент службы хранилища Azure использует строку подключения с целью хранения конечных точек и учетных данных для доступа к службам управления данными. При работе в клиентском приложении необходимо указать для хранилища строку подключения в следующем формате, используя имя своей учетной записи хранения и ключ доступа для учетной записи хранения, указанные на портале Azure значениями AccountName и AccountKey. Сведения об учетных записях хранения и ключах доступа см. в статье Об учетных записях хранения Azure. В этом примере показано, как объявить статическое поле для размещения строки подключения:
// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));
Чтобы протестировать приложение на локальном компьютере Windows, можно использовать эмулятор хранения Azurite. Azurite — это служебная программа, моделирующая службы Хранилища BLOB-объектов и очередей, доступных в Azure на локальном компьютере разработки. В следующем примере показано, как объявить статическое поле для размещения строки подключения для эмулятора локального хранилища.
// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));
Сведения о том, как запустить Azurite, см. в статье Использование эмулятора Azurite для разработки локальной службы хранилища Azure.
В приведенных ниже примерах предполагается, что вы использовали одно из этих двух определений для получения строки подключения к хранилищу.
Получить строку подключения
Информацию о своей учетной записи хранения можно представить с помощью класса cloud_storage_account. Чтобы получить данные учетной записи хранения из строки подключения хранилища, можно использовать метод parse.
// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
Практическое руководство. Создание очереди
Объект cloud_queue_client позволяет ссылаться на объекты очередей. Следующий код создает объект cloud_queue_client.
// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create a queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
С помощью объекта cloud_queue_client получите ссылку на очередь, которую необходимо использовать. Очередь можно создать, если она не существует.
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Create the queue if it doesn't already exist.
queue.create_if_not_exists();
Практическое руководство. Вставка сообщения в очередь
Чтобы вставить сообщение в существующую очередь, сначала создайте новый объект cloud_queue_message. Затем вызовите метод add_message. cloud_queue_message можно создать либо из строки (в формате UTF-8), либо из массива байтов. Ниже приведен код, который создает очередь (если она не существует) и вставляет сообщение Hello, World:
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Create the queue if it doesn't already exist.
queue.create_if_not_exists();
// Create a message and add it to the queue.
azure::storage::cloud_queue_message message1(U("Hello, World"));
queue.add_message(message1);
Практическое руководство. Просмотр следующего сообщения
Вы можете просмотреть сообщение в начале очереди, не удаляя его из очереди, с помощью метода peek_message.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Peek at the next message.
azure::storage::cloud_queue_message peeked_message = queue.peek_message();
// Output the message content.
std::wcout << U("Peeked message content: ") << peeked_message.content_as_string() << std::endl;
Практическое руководство. Изменение содержимого сообщения в очереди
Вы можете изменить содержимое сообщения непосредственно в очереди. Если сообщение представляет собой рабочую задачу, можно использовать эту функцию для обновления состояния рабочей задачи. Следующий код добавляет новое содержимое в очередь сообщений и продлевает время ожидания видимости еще на 60 секунд. Это сохраняет состояние работы, связанной с данным сообщением, и позволяет клиенту продолжить работу с сообщением на протяжении еще одной минуты. Этот метод можно использовать для отслеживания многошаговых рабочих процессов по сообщениям в очереди без необходимости начинать с самого начала в случае сбоя шага обработки в связи с ошибкой аппаратного или программного обеспечения. Обычно также сохраняется счетчик повторов; если количество повторов сообщения превысит n раз, его нужно удалить. Это обеспечивает защиту от сообщений, которые инициируют ошибку приложения при каждой попытке обработки.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Get the message from the queue and update the message contents.
// The visibility timeout "0" means make it visible immediately.
// The visibility timeout "60" means the client can get another minute to continue
// working on the message.
azure::storage::cloud_queue_message changed_message = queue.get_message();
changed_message.set_content(U("Changed message"));
queue.update_message(changed_message, std::chrono::seconds(60), true);
// Output the message content.
std::wcout << U("Changed message content: ") << changed_message.content_as_string() << std::endl;
Практическое руководство. Удаление следующего сообщения из очереди
Код удаляет сообщение из очереди в два этапа. При вызове метода get_message вы получаете следующее сообщение в очереди. Сообщение, возвращаемое методом get_message, становится невидимым для другого кода, считывающего сообщения из этой очереди. Чтобы завершить удаление сообщения из очереди, необходимо также вызвать метод delete_message. Этот двухэтапный процесс удаления сообщения позволяет удостовериться, что если коду не удастся обработать сообщение из-за сбоя оборудования или программного обеспечения, другой экземпляр кода сможет получить то же сообщение и повторить попытку. Код вызывает delete_message сразу после обработки сообщения.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Get the next message.
azure::storage::cloud_queue_message dequeued_message = queue.get_message();
std::wcout << U("Dequeued message: ") << dequeued_message.content_as_string() << std::endl;
// Delete the message.
queue.delete_message(dequeued_message);
Практическое руководство: дополнительные варианты удаления сообщений из очереди
Способ извлечения сообщения из очереди можно настроить двумя способами. Во-первых, можно получить пакет сообщений (до 32 сообщений). Во-вторых, можно задать более длительное или короткое время ожидания видимости, чтобы предоставить коду больше или меньше времени на полную обработку каждого сообщения. В следующем примере кода метод get_messages используется для получения 20 сообщений в одном вызове. Затем он обрабатывает каждое сообщение с помощью цикла for. Он также задает время ожидания невидимости 5 минут для каждого сообщения. Обратите внимание на то, что пятиминутный период начинается для всех сообщений одновременно, поэтому по прошествии пяти минут с момента вызова get_messages все сообщения, которые не были удалены, снова становятся видимыми.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Dequeue some queue messages (maximum 32 at a time) and set their visibility timeout to
// 5 minutes (300 seconds).
azure::storage::queue_request_options options;
azure::storage::operation_context context;
// Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
std::vector<azure::storage::cloud_queue_message> messages = queue.get_messages(20, std::chrono::seconds(300), options, context);
for (auto it = messages.cbegin(); it != messages.cend(); ++it)
{
// Display the contents of the message.
std::wcout << U("Get: ") << it->content_as_string() << std::endl;
}
Практическое руководство. Получение длины очереди
Вы можете узнать приблизительное количество сообщений в очереди. Метод download_attributes возвращает свойства очереди, включая число сообщений. Метод approximate_message_count возвращает приблизительное количество сообщений в очереди.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// Fetch the queue attributes.
queue.download_attributes();
// Retrieve the cached approximate message count.
int cachedMessageCount = queue.approximate_message_count();
// Display number of messages.
std::wcout << U("Number of messages in queue: ") << cachedMessageCount << std::endl;
Практическое руководство. Удаление очереди
Чтобы удалить очередь и все сообщения в ней, вызовите метод delete_queue_if_exists для объекта очереди.
// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();
// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));
// If the queue exists and delete it.
queue.delete_queue_if_exists();
Дальнейшие действия
Теперь, когда вы ознакомились с основными сведениями о хранилище очередей, используйте следующие ссылки для получения дополнительных сведений о хранилище Azure.