Uso del almacenamiento de colas de JavaHow to use Queue storage from Java

Sugerencia

Extraer del repositorio ejemplos de código de Azure StorageCheck out the Azure Storage code samples repository

Para encontrar ejemplos de código de Azure Storage de un extremo a otro y fáciles de usar que se pueden descargar y ejecutar, consulte nuestra lista de ejemplos de Azure Storage.For easy-to-use end-to-end Azure Storage code samples that you can download and run, please check out our list of Azure Storage Samples.

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 Java y utilizan el SDK de Azure Storage para Java.The samples are written in Java and use the Azure Storage SDK for Java. 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. Para obtener más información sobre las colas, consulte la sección Pasos siguientes .For more information on queues, see the Next steps section.

Nota: hay un SDK disponible para los desarrolladores que usen Azure Storage en dispositivos Android.Note: An SDK is available for developers who are using Azure Storage on Android devices. Para obtener más información, vea el SDK de Azure Storage para Android.For more information, see the Azure Storage SDK for Android.

¿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 JavaCreate a Java application

En esta guía utilizará funciones del almacenamiento que puede ejecutar en una aplicación Java localmente o bien mediante código a través de un rol web o un rol de trabajo de Azure.In this guide, you will use storage features which can be run within a Java application locally, or in code running within a web role or worker role in Azure.

Para ello, deberá instalar el Kit de desarrollo de Java (JDK) y crear una cuenta de almacenamiento de Azure en su suscripción de Azure.To do so, you will need to install the Java Development Kit (JDK) and create an Azure storage account in your Azure subscription. Después, deberá verificar que su sistema de desarrollo satisface los requisitos mínimos y las dependencias que se indican en el repositorio del SDK de Azure Storage para Java en GitHub.Once you have done so, you will need to verify that your development system meets the minimum requirements and dependencies which are listed in the Azure Storage SDK for Java repository on GitHub. Si su sistema cumple esos requisitos, puede seguir las instrucciones para descargar e instalar las bibliotecas de Azure Storage para Java en su sistema desde ese repositorio.If your system meets those requirements, you can follow the instructions for downloading and installing the Azure Storage Libraries for Java on your system from that repository. Cuando haya completado esas tareas, podrá crear una aplicación Java que use los ejemplos de este artículo.Once you have completed those tasks, you will be able to create a Java application which uses the examples in this article.

Configuración de la aplicación para obtener acceso al almacenamiento en colaConfigure your application to access queue storage

Agregue las siguientes instrucciones de importación en la parte superior del archivo Java en el que desea utilizar las API de almacenamiento de Azure para obtener acceso a las colas:Add the following import statements to the top of the Java file where you want to use Azure storage APIs to access queues:

// Include the following imports to use queue APIs.
import com.microsoft.azure.storage.*;
import com.microsoft.azure.storage.queue.*;

Configuración de una cadena de conexión de almacenamiento de AzureSetup 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 principal 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 Primary access key for the storage account listed in the Azure Portal for the AccountName and AccountKey values. 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.
public static final String storageConnectionString =
    "DefaultEndpointsProtocol=http;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key";

En una aplicación que se esté ejecutando en un rol de Microsoft Azure, esta cadena se puede almacenar en el archivo de configuración de servicio, ServiceConfiguration.cscfg, y se puede obtener acceso a él con una llamada al método RoleEnvironment.getConfigurationSettings .In an application running within a role in Microsoft Azure, this string can be stored in the service configuration file, ServiceConfiguration.cscfg, and can be accessed with a call to the RoleEnvironment.getConfigurationSettings method. A continuación se muestra un ejemplo de cómo obtener la cadena de conexión desde un elemento de configuración denominado StorageConnectionString en el archivo de configuración del servicio:Here's an example of getting the connection string from a Setting element named StorageConnectionString in the service configuration file:

// Retrieve storage account from connection-string.
String storageConnectionString =
    RoleEnvironment.getConfigurationSettings().get("StorageConnectionString");

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.

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

Los objetos CloudQueueClient le permiten obtener objetos de referencia para las colas.A CloudQueueClient object lets you get reference objects for queues. El siguiente código crea un objeto CloudQueueClient.The following code creates a CloudQueueClient object. (Nota: Existen otras maneras de crear objetos CloudStorageAccount. Para más información, consulte CloudStorageAccount en la referencia del SDK del cliente de Azure Storage.(Note: There are additional ways to create CloudStorageAccount objects; for more information, see CloudStorageAccount in the Azure Storage Client SDK Reference.)

Use el objeto CloudQueueClient para obtener una referencia a la cola que desea utilizar.Use the CloudQueueClient 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.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

   // Create the queue client.
   CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

   // Retrieve a reference to a queue.
   CloudQueue queue = queueClient.getQueueReference("myqueue");

   // Create the queue if it doesn't already exist.
   queue.createIfNotExists();
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Procedimientos para: un mensaje a una colaHow to: Add a message to a queue

Para insertar un mensaje en una cola existente, cree en primer lugar un nuevo CloudQueueMessage.To insert a message into an existing queue, first create a new CloudQueueMessage. A continuación, llame al método addMessage .Next, call the addMessage method. Se puede crear un CloudQueueMessage a partir de una cadena (en formato UTF-8) o de una matriz de bytes.A CloudQueueMessage can be created from either a string (in UTF-8 format) 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".

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Create the queue if it doesn't already exist.
    queue.createIfNotExists();

    // Create a message and add it to the queue.
    CloudQueueMessage message = new CloudQueueMessage("Hello, World");
    queue.addMessage(message);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Procedimientos para: siguiente mensajeHow to: Peek at the next message

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

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Peek at the next message.
    CloudQueueMessage peekedMessage = queue.peekMessage();

    // Output the message value.
    if (peekedMessage != null)
    {
      System.out.println(peekedMessage.getMessageContentAsString());
   }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

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.

El siguiente código de ejemplo busca en la cola de mensajes, encuentra el primer mensaje cuyo contenido coincide con "Hola, mundo" y luego modifica el contenido del mensaje "Hola mundo" y se cierra.The following code sample searches through the queue of messages, locates the first message that matches "Hello, World" for the content, then modifies the message content and exits.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // The maximum number of messages that can be retrieved is 32.
    final int MAX_NUMBER_OF_MESSAGES_TO_PEEK = 32;

    // Loop through the messages in the queue.
    for (CloudQueueMessage message : queue.retrieveMessages(MAX_NUMBER_OF_MESSAGES_TO_PEEK,1,null,null))
    {
        // Check for a specific string.
        if (message.getMessageContentAsString().equals("Hello, World"))
        {
            // Modify the content of the first matching message.
            message.setMessageContent("Updated contents.");
            // Set it to be visible in 30 seconds.
            EnumSet<MessageUpdateFields> updateFields =
                EnumSet.of(MessageUpdateFields.CONTENT,
                MessageUpdateFields.VISIBILITY);
            // Update the message.
            queue.updateMessage(message, 30, updateFields, null, null);
            break;
        }
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Como alternativa, el siguiente código de ejemplo actualiza únicamente el primer mensaje visible de la cola.Alternatively, the following code sample updates just the first visible message on the queue.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve the first visible message in the queue.
    CloudQueueMessage message = queue.retrieveMessage();

    if (message != null)
    {
        // Modify the message content.
        message.setMessageContent("Updated contents.");
        // Set it to be visible in 60 seconds.
        EnumSet<MessageUpdateFields> updateFields =
            EnumSet.of(MessageUpdateFields.CONTENT,
            MessageUpdateFields.VISIBILITY);
        // Update the message.
        queue.updateMessage(message, 60, updateFields, null, null);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

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 downloadAttributes pide al servicio de cola varios valores actuales, incluido un conteo de cuántos mensajes están en la cola.The downloadAttributes method asks the Queue service for several current values, including a count of how many messages are in a queue. El recuento solo es aproximado, ya que se pueden agregar o borrar mensajes después de que el servicio de cola haya respondido su solicitud.The count is only approximate because messages can be added or removed after the Queue service responds to your request. El método getApproximateMethodCount devuelve el último valor recuperado por la llamada a downloadAttributes, sin llamar a Queue service.The getApproximateMessageCount method returns the last value retrieved by the call to downloadAttributes, without calling the Queue service.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

   // Download the approximate message count from the server.
    queue.downloadAttributes();

    // Retrieve the newly cached approximate message count.
    long cachedMessageCount = queue.getApproximateMessageCount();

    // Display the queue length.
    System.out.println(String.format("Queue length: %d", cachedMessageCount));
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Procedimientos para: Extracción del siguiente mensaje de la colaHow to: Dequeue the next message

El código extrae un mensaje de una cola en dos pasos.Your code dequeues a message from a queue in two steps. Al llamar a retrieveMessage, obtiene el siguiente mensaje de una cola.When you call retrieveMessage, you get the next message in a queue. Un mensaje devuelto por retrieveMessage se hace invisible a cualquier otro código de lectura de mensajes de esta cola.A message returned from retrieveMessage becomes invisible to any other code reading messages from this queue. De forma predeterminada, este mensaje permanece invisible durante 30 segundos.By default, this message stays invisible for 30 seconds. Para terminar de quitar el mensaje de la cola, también debe llamar a deleteMessage.To finish removing the message from the queue, you must also call deleteMessage. 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.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. Su código llama a deleteMessage justo después de que se haya procesado el mensaje.Your code calls deleteMessage right after the message has been processed.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve the first visible message in the queue.
    CloudQueueMessage retrievedMessage = queue.retrieveMessage();

    if (retrievedMessage != null)
    {
        // Process the message in less than 30 seconds, and then delete the message.
        queue.deleteMessage(retrievedMessage);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Opciones adicionales para quitar mensajes de la colaAdditional options for dequeuing 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 retrieveMessage para obtener 20 mensajes en una llamada.The following code example uses the retrieveMessages 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 (300 segundos) para cada mensaje.It also sets the invisibility timeout to five minutes (300 seconds) for each message. Tenga en cuenta que los cinco minutos empiezan a contar para todos los mensajes al mismo tiempo, por lo que después de pasar los cinco minutos desde la llamada a retrieveMessage, todos los mensajes que no se han eliminado volverán a estar visibles.Note that the five minutes starts for all messages at the same time, so when five minutes have passed since the call to retrieveMessages, any messages which have not been deleted will become visible again.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
    for (CloudQueueMessage message : queue.retrieveMessages(20, 300, null, null)) {
        // Do processing for all messages in less than 5 minutes,
        // deleting each message after processing.
        queue.deleteMessage(message);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Procedimientos para: Enumeración de las colasHow to: List the queues

Para obtener una lista de las colas actuales, llame al método CloudQueueClient.listQueues(), el cual devolverá una colección de objetos CloudQueue.To obtain a list of the current queues, call the CloudQueueClient.listQueues() method, which will return a collection of CloudQueue objects.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient =
        storageAccount.createCloudQueueClient();

    // Loop through the collection of queues.
    for (CloudQueue queue : queueClient.listQueues())
    {
        // Output each queue name.
        System.out.println(queue.getName());
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

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 deleteIfExists en el objeto de cola CloudQueue.To delete a queue and all the messages contained in it, call the deleteIfExists method on the CloudQueue object.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Delete the queue if it exists.
    queue.deleteIfExists();
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Pasos siguientesNext steps

Ahora que está familiarizado con los aspectos básicos del almacenamiento de colas, utilice estos vínculos para obtener más información acerca de tareas de almacenamiento más complejas.Now that you've learned the basics of queue storage, follow these links to learn about more complex storage tasks.