Uso de Queue Storage de C++How to use Queue Storage from C++

Sugerencia

Probar el Explorador de Microsoft Azure StorageTry the Microsoft Azure Storage Explorer

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.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Información generalOverview

Esta guía muestra cómo realizar algunas tareas comunes a través del servicio de almacenamiento en cola de Azure.This guide will show you how to perform common scenarios using the Azure Queue storage service. Los ejemplos están escritos en C++ y usan la biblioteca de cliente de Azure Storage para C++.The samples are written in C++ and use the Azure Storage Client Library for C++. Entre los escenarios descritos se incluyen insertar, ojear, obtener y eliminar mensajes de la cola, así como crear y eliminar colas.The scenarios covered include inserting, peeking, getting, and deleting queue messages, as well as creating and deleting queues.

Nota

Esta guía se destina a la biblioteca de cliente de Azure Storage para C++, versión 1.0.0 y posteriores.This guide targets the Azure Storage Client Library for C++ version 1.0.0 and above. La versión recomendada es la biblioteca de cliente de almacenamiento 2.2.0, que se encuentra disponible a través de NuGet o GitHub.The recommended version is Storage Client Library 2.2.0, which is available via NuGet or GitHub.

¿Qué es Queue Storage?What is 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.Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or 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.A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

El almacenamiento en cola suele usarse para realizar las siguientes tareas:Common uses of Queue storage include:

  • Creación de trabajo pendiente para el procesamiento asincrónicoCreating a backlog of work to process asynchronously
  • Transferencia de mensajes de un rol web de Azure a un rol de trabajo de AzurePassing messages from an Azure web role to an Azure worker role

Conceptos del servicio ColaQueue Service Concepts

El servicio Cola contiene los siguientes componentes:The Queue service contains the following components:

Cola1

  • Formato de dirección URL: Las colas son direccionables mediante el siguiente formato de dirección URL:URL format: Queues are addressable using the following URL format:
    http://<storage account>.queue.core.windows.net/<queue>http://<storage account>.queue.core.windows.net/<queue>

    La siguiente dirección URL dirige a una cola del diagrama:The following URL addresses a queue in the diagram:

    http://myaccount.queue.core.windows.net/images-to-download

  • Cuenta de almacenamiento: Todo el acceso a Azure Storage se realiza a través de una cuenta de almacenamiento.Storage Account: All access to Azure Storage is done through a storage account. Consulte Objetivos de escalabilidad y rendimiento de Azure Storage para obtener información sobre la capacidad de la cuenta de almacenamiento.See Azure Storage Scalability and Performance Targets for details about storage account capacity.

  • Cola: una cola contiene un conjunto de mensajes.Queue: A queue contains a set of messages. Todos los mensajes deben encontrarse en una cola.All messages must be in a queue. Tenga en cuenta que el nombre de la cola debe ir en minúsculas.Note that the queue name must be all lowercase. Para más información, consulte Asignar nombres a colas y metadatos.For information on naming queues, see Naming Queues and Metadata.

  • Mensaje: un mensaje, en cualquier formato, de hasta 64 KB.Message: A message, in any format, of up to 64 KB. El tiempo máximo que un mensaje puede permanecer en la cola es de 7 días.The maximum time that a message can remain in the queue is 7 days.

Creación de una cuenta de Azure StorageCreate an Azure storage account

La forma más fácil de crear la primera cuenta de Azure Storage es a través de Azure Portal.The easiest way to create your first Azure storage account is by using the Azure portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.To learn more, see Create a storage account.

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.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Si no desea crear una cuenta de almacenamiento en Azure en este momento, también puede utilizar el emulador de Azure Storage para ejecutar y probar el código en un entorno local.If you prefer not to create a storage account in Azure at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure Storage Emulator for Development and Testing.

Creación de una aplicación de C++Create a C++ application

En esta guía, usará las características de almacenamiento que se pueden ejecutar en una aplicación C++.In this guide, you will use storage features which can be run within a C++ application.

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.To do so, you will need to install the Azure Storage Client Library for C++ and create an Azure storage account in your Azure subscription.

Para instalar la biblioteca de cliente de Azure Storage para C++, puede usar los métodos siguientes:To install the Azure Storage Client Library for C++, you can use the following methods:

Install-Package wastorage

Configuración de la aplicación para obtener acceso a Queue StorageConfigure your application to access Queue Storage

Agregue las siguientes instrucciones include en la parte superior del archivo C++ en el que desea usar las API de almacenamiento de Azure para obtener acceso a las colas:Add the following include statements to the top of the C++ file where you want to use the Azure storage APIs to access queues:

#include <was/storage_account.h>
#include <was/queue.h>

Configuración de una cadena de conexión de Almacenamiento de AzureSet up an Azure storage connection string

Un cliente de almacenamiento de Azure utiliza 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.An Azure storage client uses a storage connection string to store endpoints and credentials for accessing data management services. 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.When running in a client application, you must provide the storage connection string in the following format, using the name of your storage account and the storage access key for the storage account listed in the Azure Portal for the AccountName and AccountKey values. Para obtener información sobre las cuentas de almacenamiento y las claves de acceso, consulte Acerca de las cuentas de Azure Storage.For information on storage accounts and access keys, see About Azure Storage Accounts. En este ejemplo se muestra cómo puede declarar un campo estático para mantener la cadena de conexión:This example shows how you can declare a static field to hold the connection string:

// 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 local de Windows, puede usar Microsoft Azure Storage Emulator que se instala con Azure SDK.To test your application in your local Windows computer, you can use the Microsoft Azure storage emulator that is installed with the Azure SDK. El emulador de almacenamiento es una utilidad que simula los servicios Blob, Queue y Table de Azure en el equipo de desarrollo local.The storage emulator is a utility that simulates the Blob, Queue, and Table services available in Azure on your local development machine. 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:The following example shows how you can declare a static field to hold the connection string to your local storage emulator:

// Define the connection-string with Azure Storage Emulator.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));  

Para iniciar Azure Storage Emulator, seleccione el botón Inicio o pulse la tecla Windows.To start the Azure storage emulator, select the Start button or press the Windows key. Comience a escribir Azure Storage Emulator y seleccione Emulador de Microsoft Azure Storage en la lista de aplicaciones.Begin typing Azure Storage Emulator, and select Microsoft Azure Storage Emulator from the list of applications.

En los ejemplos siguientes se supone que usó uno de estos dos métodos para obtener la cadena de conexión de almacenamiento.The following samples assume that you have used one of these two methods to get the storage connection string.

Recuperación de la cadena de conexiónRetrieve your connection string

Puede usar la clase cloud_storage_account para representar la información de la cuenta de almacenamiento.You can use the cloud_storage_account class to represent your Storage Account information. 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 .To retrieve your storage account information from the storage connection string, you can use the parse method.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

Procedimientos para: Creación de una colaHow to: Create a queue

Los objetos cloud_queue_client le permiten obtener objetos de referencia para las colas.A cloud_queue_client object lets you get reference objects for queues. El siguiente código crea un objeto cloud_queue_client.The following code creates a cloud_queue_client object.

// 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 usar.Use the cloud_queue_client object to get a reference to the queue you want to use. En caso de que la cola no exista todavía, es posible crearla.You can create the queue if it doesn't exist.

// 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 para: un mensaje en una colaHow to: Insert a message into a queue

Para insertar un mensaje en una cola existente, cree en primer lugar un nuevo cloud_queue_message.To insert a message into an existing queue, first create a new cloud_queue_message. A continuación, llame al método add_message.Next, call the add_message method. Se puede crear un cloud_queue_message a partir de una cadena o de una matriz de byte.A cloud_queue_message can be created from either a string or a byte array. A continuación se muestra el código con el que se crea una cola (si no existe) y se inserta el mensaje "Hola, mundo":Here is code which creates a queue (if it doesn't exist) and inserts the message '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 para: siguiente mensajeHow to: Peek at the next message

Puede ojear el mensaje situado en la parte delantera de una cola, sin quitarlo de la cola, llamando al método peek_message.You can peek at the message in the front of a queue without removing it from the queue by calling the peek_message method.

// 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 para: contenido de un mensaje en colaHow to: Change the contents of a queued message

Puede cambiar el contenido de un mensaje local en la cola.You can change the contents of a message in-place in the queue. Si el mensaje representa una tarea de trabajo, puede usar esta característica para actualizar el estado de la tarea de trabajo.If the message represents a work task, you could use this feature to update the status of the work task. 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.The following code updates the queue message with new contents, and sets the visibility timeout to extend another 60 seconds. 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.This saves the state of work associated with the message, and gives the client another minute to continue working on the message. 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.You could use this technique to track multi-step workflows on queue messages, without having to start over from the beginning if a processing step fails due to hardware or software failure. Normalmente, también mantendría un número de reintentos y, si el mensaje se intentara más de n veces, lo eliminaría.Typically, you would keep a retry count as well, and if the message is retried more than n times, you would delete it. Esto proporciona protección frente a un mensaje que produce un error en la aplicación cada vez que se procesa.This protects against a message that triggers an application error each time it is processed.

// 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 para: siguiente mensaje de la colaHow to: De-queue the next message

El código quita un mensaje de una cola en dos pasos.Your code de-queues a message from a queue in two steps. Si se llama a get_message, obtiene el siguiente mensaje de una cola.When you call get_message, you get the next message in a queue. Un mensaje devuelto por get_message se hace invisible a cualquier otro código que lea mensajes de esta cola.A message returned from get_message becomes invisible to any other code reading messages from this queue. Para terminar quitando el mensaje de la cola, también debe llamar a delete_message.To finish removing the message from the queue, you must also call delete_message. Este proceso 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.This two-step process of removing a message assures that if your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. El código llama a delete_message justo después de que se haya procesado el mensaje.Your code calls delete_message right after the message has been processed.

// 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);

Procedimientos para: Uso de opciones adicionales para quitar mensajes de la colaHow to: Leverage additional options for de-queuing messages

Hay dos formas de personalizar la recuperación de mensajes de una cola.There are two ways you can customize message retrieval from a queue. En primer lugar, puede obtener un lote de mensajes (hasta 32).First, you can get a batch of messages (up to 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.Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message. El siguiente ejemplo de código utiliza el método get_messages para obtener 20 mensajes en una llamada.The following code example uses the get_messages method to get 20 messages in one call. A continuación, procesa cada mensaje con un bucle for .Then it processes each message using a for loop. También establece el tiempo de espera de la invisibilidad en cinco minutos para cada mensaje.It also sets the invisibility timeout to five minutes for each message. Tenga en cuenta que los 5 minutos empiezan a contar para todos los mensajes al mismo tiempo, por lo que después de que pasen los 5 minutos desde la llamada a get_messages, todos los mensajes que no se han eliminado volverán a estar visibles.Note that the 5 minutes starts for all messages at the same time, so after 5 minutes have passed since the call to get_messages, any messages which have not been deleted will become visible again.

// 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 para: la longitud de la colaHow to: Get the queue length

Puede obtener una estimación del número de mensajes existentes en una cola.You can get an estimate of the number of messages in a queue. El método download_attributes solicita a Queue service la recuperación de los atributos de la cola, incluido el número de mensajes.The download_attributes method asks the Queue service to retrieve the queue attributes, including the message count. El método approximate_message_count obtiene el número aproximado de mensajes en la cola.The approximate_message_count method gets the approximate number of messages in the queue.

// 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 para: Eliminación de una colaHow to: Delete a queue

Para eliminar una cola y todos los mensajes contenidos en ella, llame al método delete_queue_if_exists en el objeto de cola.To delete a queue and all the messages contained in it, call the delete_queue_if_exists method on the queue object.

// 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 siguientesNext steps

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.Now that you've learned the basics of Queue storage, follow these links to learn more about Azure Storage.