Uso de Queue Storage de C++
Sugerencia
Probar el Explorador de Microsoft Azure Storage
El Explorador de Microsoft Azure Storage es una aplicación independiente y gratuita de Microsoft que permite trabajar visualmente con los datos de Azure Storage en Windows, macOS y Linux.
Información general
Esta guía muestra cómo realizar algunas tareas comunes a través del servicio Azure Queue Storage. Los ejemplos están escritos en C++ y usan la biblioteca de cliente de Azure Storage para C++. Entre los escenarios descritos se incluyen insertar, ojear, obtener y eliminar mensajes de la cola, así como crear y eliminar colas.
Nota:
Esta guía se destina a la biblioteca de cliente de Azure Storage para C++, versión 1.0.0 y posteriores. La versión recomendada es la biblioteca de cliente de Azure Storage 2.2.0, que se encuentra disponible a través de NuGet o GitHub.
¿Qué es Queue Storage?
El almacenamiento en cola de Azure es un servicio para almacenar grandes cantidades de mensajes a los que puede obtenerse acceso desde cualquier lugar del mundo a través de llamadas autenticadas con HTTP o HTTPS. Un único mensaje en cola puede tener un tamaño de hasta 64 KB y una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento. Queue Storage se usa normalmente para crear un trabajo pendiente del trabajo que se va a procesar de forma asincrónica.
Conceptos del servicio Queue
Azure Queue service contiene los siguientes componentes:
Cuenta de almacenamiento: Todo el acceso a Azure Storage se realiza a través de una cuenta de almacenamiento. Para más información sobre las cuentas de almacenamiento, consulte Introducción a las cuentas de Storage.
Cola: una cola contiene un conjunto de mensajes. Todos los mensajes deben encontrarse en una cola. Tenga en cuenta que el nombre de la cola debe ir en minúsculas. Para más información, consulte Asignar nombres a colas y metadatos.
Mensaje: un mensaje, en cualquier formato, de hasta 64 KB. El tiempo máximo que un mensaje puede permanecer en la cola es de 7 días. A partir de la versión del 2017-07-29, inclusive, el tiempo de vida máximo puede ser cualquier número positivo o -1, lo que indica que el mensaje no expira. Si se omite este parámetro, el tiempo de vida predeterminado es siete días.
Formato de URL: las colas son direccionables mediante el siguiente formato de dirección URL: http://
<storage account>.queue.core.windows.net/<queue>La siguiente dirección URL dirige a una cola del diagrama:
http://myaccount.queue.core.windows.net/incoming-orders
Creación de una cuenta de Azure Storage
La forma más fácil de crear la primera cuenta de Azure Storage es a través de Azure Portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.
Puede crear también una cuenta de Azure Storage mediante Azure PowerShell, la CLI de Azure o el proveedor de recursos de Azure Storage para .NET.
Si no quiere crear una cuenta de almacenamiento en Azure en este momento, también puede utilizar el emulador de almacenamiento Azurite para ejecutar y probar el código en un entorno local. Para más información, consulte Uso del emulador de Azurite para desarrollo y pruebas locales de Azure Storage.
Creación de una aplicación de C++
En esta guía, usará las características de almacenamiento que se pueden ejecutar en una aplicación C++.
Para ello, deberá instalar la biblioteca de cliente de Azure Storage para C++ y crear una cuenta de Azure Storage en su suscripción de Azure.
Para instalar la biblioteca de cliente de Azure Storage para C++, puede usar los métodos siguientes:
- Linux: siga las instrucciones indicadas en Léame de la biblioteca de cliente de Azure Storage para C++: Getting Started on Linux page.
- Windows: En Windows, use vcpkg como administrador de dependencias. Siga el inicio rápido para inicializar
vcpkg. Después, use el comando siguiente para instalar la biblioteca:
.\vcpkg.exe install azure-storage-cpp
Puede encontrar una guía sobre cómo compilar el código fuente y exportarlo a NuGet en el archivo Léame.
Configuración de la aplicación para obtener acceso a Queue Storage
Agregue las siguientes instrucciones include en la parte superior del archivo C++ en el que desea usar las API de Azure Storage para obtener acceso a las colas:
#include <was/storage_account.h>
#include <was/queue.h>
Configuración de una cadena de conexión de Azure Storage
Un cliente de Azure Storage usa una cadena de conexión de almacenamiento para almacenar extremos y credenciales con el fin de obtener acceso a los servicios de administración de datos. Al ejecutarse en una aplicación cliente, debe proporcionar la cadena de conexión de almacenamiento en el siguiente formato, usando el nombre de su cuenta de almacenamiento y la clave de acceso de almacenamiento de la cuenta de almacenamiento que se muestra en Azure Portal para los valores AccountName y AccountKey. Para obtener información sobre las cuentas de Storage y las claves de acceso, consulte Acerca de las cuentas de Azure Storage. En este ejemplo se muestra cómo puede declarar un campo estático para mantener la cadena de conexión:
// 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"));
Para probar la aplicación en el equipo Windows local, puede usar el emulador de almacenamiento Azurite. Azurite es una utilidad que simula Azure Blob Storage y Queue Storage en el equipo de desarrollo local. En el ejemplo siguiente se muestra cómo puede declarar un campo estático para mantener la cadena de conexión en el emulador de almacenamiento local:
// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));
Para iniciar Azurite, consulte Uso del emulador de Azurite para desarrollo local de Azure Storage.
En los ejemplos siguientes se supone que usó uno de estos dos métodos para obtener la cadena de conexión de almacenamiento.
Recuperación de la cadena de conexión
Puede usar la clase cloud_storage_account para representar la información de la cuenta de almacenamiento. Para recuperar la información de la cuenta de almacenamiento a partir de la cadena de conexión de almacenamiento, puede usar el método parse.
// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);
Procedimientos: Creación de una cola
Los objetos cloud_queue_client le permiten obtener objetos de referencia para las colas. El código siguiente crea un objeto 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();
Use el objeto cloud_queue_client para obtener una referencia a la cola que desea utilizar. En caso de que la cola no exista todavía, es posible crearla.
// 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();
Procedimientos: un mensaje en una cola
Para insertar un mensaje en una cola existente, cree en primer lugar un nuevo cloud_queue_message. A continuación, llame al método add_message. Se puede crear un objeto cloud_queue_message a partir de una cadena (en formato UTF-8) o de una matriz de bytes. A continuación, se muestra el código con el que se crea una cola (si no existe) y se inserta el mensaje 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);
Procedimientos: siguiente mensaje
Puede inspeccionar el mensaje situado en la parte delantera de una cola, sin quitarlo de la cola, mediante una llamada al método 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;
Procedimientos: contenido de un mensaje en cola
Puede cambiar el contenido de un mensaje local en la cola. Si el mensaje representa una tarea de trabajo, puede usar esta característica para actualizar el estado de la tarea de trabajo. El siguiente código actualiza el mensaje de la cola con contenido nuevo y amplía el tiempo de espera de la visibilidad en 60 segundos más. De este modo, se guarda el estado de trabajo asociado al mensaje y se le proporciona al cliente un minuto más para que siga elaborando el mensaje. Esta técnica se puede utilizar para realizar un seguimiento de los flujos de trabajo de varios pasos en los mensajes en cola, sin que sea necesario volver a empezar desde el principio si se produce un error en un paso del proceso a causa de un error de hardware o software. Normalmente, también mantendría un número de reintentos y, si el mensaje se intentara más de n veces, lo eliminaría. Esto proporciona protección frente a un mensaje que produce un error en la aplicación cada vez que se procesa.
// 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;
Procedimientos: Extracción del siguiente mensaje de la cola
El código extrae un mensaje de una cola en dos pasos. Al llamar a get_message, obtiene el siguiente mensaje de una cola. Un mensaje devuelto por get_message se hace invisible a cualquier otro código de lectura de mensajes de esta cola. Para terminar quitando el mensaje de la cola, también debe llamar a delete_message. Este proceso de extracción de un mensaje que consta de dos pasos garantiza que si su código no puede procesar un mensaje a causa de un error de hardware o software, otra instancia de su código puede obtener el mismo mensaje e intentarlo de nuevo. El código siguiente llama a delete_message justo después de haberse procesado el mensaje.
// 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);
Procedimiento: Uso de opciones adicionales para quitar mensajes de la cola
Hay dos formas de personalizar la recuperación de mensajes de una cola. En primer lugar, puede obtener un lote de mensajes (hasta 32). En segundo lugar, puede establecer un tiempo de espera de la invisibilidad más largo o más corto para que el código disponga de más o menos tiempo para procesar cada mensaje. El siguiente ejemplo de código utiliza el método get_messages para obtener veinte mensajes en una llamada. A continuación, procesa cada mensaje con un bucle for. También establece el tiempo de espera de la invisibilidad en cinco minutos para cada mensaje. Tenga en cuenta que los 5 minutos empiezan a contar para todos los mensajes al mismo tiempo, por lo que después de pasar los 5 minutos desde la llamada a get_messages, todos los mensajes que no se han eliminado volverán a estar visibles.
// 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;
}
Procedimientos: la longitud de la cola
Puede obtener una estimación del número de mensajes existentes en una cola. El método download_attributes devuelve propiedades de cola, incluido el recuento de mensajes. El método approximate_message_count obtiene el número aproximado de mensajes en la cola.
// 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;
Procedimientos: Eliminación de una cola
Para eliminar una cola y todos los mensajes que contiene, llame al método delete_queue_if_exists en el objeto de cola.
// 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();
Pasos siguientes
Ahora que está familiarizado con los aspectos básicos de Queue Storage, siga estos vínculos para obtener más información sobre Azure Storage.