Inicio rápido: Biblioteca cliente de Azure Queue Storage v12 para Java

Empiece a usar la biblioteca cliente de Azure Queue Storage v12 para Java. Azure Queue Storage es un servicio para almacenar gran cantidad de mensajes para su posterior recuperación y procesamiento. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Use la biblioteca cliente de Azure Queue Storage v12 para Java para realizar las siguientes operaciones:

  • Creación de una cola
  • Adición de mensajes a una cola
  • Lectura de los mensajes de una cola
  • Eliminación de un mensaje de una cola
  • Recepción y eliminación de mensajes de una cola
  • Eliminación de una cola

Recursos adicionales:

Requisitos previos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Queue Storage v12 para Java.

Creación del proyecto

Cree una aplicación de Java llamada queues-quickstart-v12.

  1. En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use Maven para crear una nueva aplicación de consola con el nombre queues-quickstart-v12. Escriba el siguiente comando mvn para crear un proyecto "Hola mundo" en Java.

    mvn archetype:generate `
        --define interactiveMode=n `
        --define groupId=com.queues.quickstart `
        --define artifactId=queues-quickstart-v12 `
        --define archetypeArtifactId=maven-archetype-quickstart `
        --define archetypeVersion=1.4
    
  2. La salida a partir de la generación del proyecto debe ser similar a la siguiente:

    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------< org.apache.maven:standalone-pom >-------------------
    [INFO] Building Maven Stub Project (No POM) 1
    [INFO] --------------------------------[ pom ]---------------------------------
    [INFO]
    [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
    [INFO]
    [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
    [INFO]
    [INFO]
    [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
    [INFO] Generating project in Batch mode
    [INFO] ----------------------------------------------------------------------------
    [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
    [INFO] ----------------------------------------------------------------------------
    [INFO] Parameter: groupId, Value: com.queues.quickstart
    [INFO] Parameter: artifactId, Value: queues-quickstart-v12
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.quickstart
    [INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.quickstart
    [INFO] Parameter: groupId, Value: com.queues.quickstart
    [INFO] Parameter: artifactId, Value: queues-quickstart-v12
    [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart-v12
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  6.394 s
    [INFO] Finished at: 2019-12-03T09:58:35-08:00
    [INFO] ------------------------------------------------------------------------
    
  3. Cambie al directorio queues-quickstart-v12 recién creado.

    cd queues-quickstart-v12
    

Instalar el paquete

Abra el archivo pom.xml en el editor de texto. Agregue el siguiente elemento de dependencia al grupo de dependencias.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-queue</artifactId>
  <version>12.0.1</version>
</dependency>

Instalación del marco de la aplicación

Desde el directorio del proyecto:

  1. Vaya al directorio /src/main/java/com/queues/quickstart
  2. Abra el archivo App.java en un editor.
  3. Eliminar la instrucción System.out.println("Hello, world");.
  4. Agregue directivas import.

Este es el código:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library v12 quickstart
 */
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;
import java.time.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
    }
}

Copia de las credenciales desde Azure Portal

Cuando la aplicación de ejemplo realiza una solicitud a Azure Storage, debe estar autorizada. Para autorizar una solicitud, agregue a la aplicación las credenciales de la cuenta de almacenamiento en forma de cadena de conexión. Para ver las credenciales de la cuenta de almacenamiento, siga estos pasos:

  1. Inicie sesión en Azure Portal.

  2. Busque su cuenta de almacenamiento.

  3. En el panel del menú de la cuenta de almacenamiento, en Seguridad y redes, seleccione Claves de acceso. Aquí puede ver las claves de acceso de la cuenta, así como la cadena de conexión completa de cada clave.

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

  4. En el panel Claves acceso, seleccione Mostrar claves.

  5. En la sección key1, busque el valor de Cadena de conexión. Seleccione el icono Copiar al portapapeles para copiar la cadena de conexión. En la siguiente sección, agregará el valor de la cadena de conexión a una variable de entorno.

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

Configuración de la cadena de conexión de almacenamiento.

Una vez que haya copiado la cadena de conexión, escríbala en una variable de entorno nueva en la máquina local que ejecuta la aplicación. Para establecer la variable de entorno, abra una ventana de consola y siga las instrucciones de su sistema operativo. Reemplace <yourconnectionstring> por la cadena de conexión real.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Después de agregar la variable de entorno en Windows, debe iniciar una nueva instancia de la ventana de comandos.

Reiniciar programas

Después de agregar la variable de entorno, reinicie todos los programas en ejecución que necesiten leer esta variable. Por ejemplo, reinicie el entorno de desarrollo o el editor antes de continuar.

Modelo de objetos

Azure Queue Storage es un servicio para almacenar grandes cantidades de mensajes, Un mensaje de la cola puede llegar a tener hasta 64 KB. Una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento. Las colas se utilizan normalmente para crear un trabajo pendiente del trabajo que se va a procesar de forma asincrónica. Queue Storage ofrece tres tipos de recursos:

  • La cuenta de almacenamiento
  • Cola en la cuenta de almacenamiento
  • Mensajes dentro de la cola

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagram of Queue storage architecture

Use las siguientes clases de Java para interactuar con estos recursos:

  • QueueClientBuilder: La clase QueueClientBuilder configura y crea instancias de un objeto QueueClient.
  • QueueServiceClient: La clase QueueServiceClient permite administrar todas las colas de la cuenta de almacenamiento.
  • QueueClient: La clase QueueClient permite administrar y manipular una cola individual y sus mensajes.
  • QueueMessageItem: La clase QueueMessageItem representa los objetos individuales que se devuelven al llamar a ReceiveMessages en una cola.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca cliente de Azure Queue Storage para Java:

Obtención de la cadena de conexión

El siguiente código recupera la cadena de conexión de la cuenta de almacenamiento. La cadena de conexión se almacena en la variable de entorno creada en la sección Configuración de la cadena de conexión de almacenamiento.

Agregue este código dentro del método main:

System.out.println("Azure Queue Storage client library v12 - Java quickstart sample\n");

// 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. If the environment variable
// is created after the application is launched in a console or with
// Visual Studio, the shell or application needs to be closed and reloaded
// to take the environment variable into account.
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

Creación de una cola

Decida un nombre para la nueva cola. El siguiente código anexa un valor de GUID al nombre de la cola para asegurarse de que sea único.

Importante

Los nombres de la cola solo puede incluir letras minúsculas, números y guiones y debe empezar por una letra o un número. Antes y después de cada guion debe ir un carácter que no sea otro guión. El nombre debe tener entre 3 y 63 caracteres. Para más información sobre la nomenclatura de las colas, consulte Asignación de nombres a colas y metadatos.

Cree una instancia de la clase QueueClient. Luego, llame al método Create para crear la cola en la cuenta de almacenamiento.

Agregue este código al final del método main:

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

System.out.println("Creating queue: " + queueName);

// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
                                .connectionString(connectStr)
                                .queueName(queueName)
                                .buildClient();

// Create the queue
queueClient.create();

Adición de mensajes a una cola

El siguiente fragmento de código agrega mensajes a la cola, para lo que debe llamar al método sendMessage. También guarda una clase SendMessageResult devuelta desde una llamada a sendMessage. El resultado se utiliza para actualizar el mensaje más adelante en el programa.

Agregue este código al final del método main:

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Lectura de los mensajes de una cola

Lea los mensajes de la cola, para lo que debe llamar al método peekMessages. Este método recupera uno o varios mensajes de la parte delantera de la cola, pero no modifica la visibilidad del mensaje.

Agregue este código al final del método main:

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Eliminación de un mensaje de una cola

Actualice el contenido de un mensaje mediante una llamada al método updateMessage. Este método puede cambiar tanto el contenido como el tiempo de espera de visibilidad de un mensaje. El contenido del mensaje debe ser una cadena con codificación UTF-8 de hasta 64 KB de tamaño. Junto con el nuevo contenido del mensaje, pase el identificador de mensaje y la recepción de confirmación mediante SendMessageResult que se guardó anteriormente en el código. El identificador de mensaje y la confirmación de extracción identifican el mensaje que se va a actualizar.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Recepción y eliminación de mensajes de una cola

Descargue los mensajes que ha agregado anteriormente, para lo que debe llamar al método receiveMessages. El código de ejemplo también elimina los mensajes de la cola una vez recibidos y procesados. En este caso, el procesamiento solo muestra el mensaje en la consola.

La aplicación se detiene para la entrada del usuario mediante una llamada a System.console().readLine(); antes de recibir y eliminar los mensajes. Compruebe en Azure Portal que los recursos se crearon correctamente, antes de que se eliminen. Los mensajes que no se eliminen explícitamente volverán a estar visibles en la cola para que se procesen.

Agregue este código al final del método main:

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Eliminación de una cola

El siguiente código limpia los recursos que creó la aplicación; para ello, elimina la cola mediante el método Delete.

Agregue este código al final del método main:

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

Ejecución del código

Esta aplicación crea y agrega tres mensajes a una cola de Azure. El código muestra los mensajes en la cola y, a continuación, los recupera y los elimina antes de eliminar la cola.

En la ventana de la consola, vaya al directorio de la aplicación y, después, compile y ejecute la aplicación.

mvn compile

A continuación, compile el paquete.

mvn package

Use el siguiente comando mvn para ejecutar la aplicación.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

La salida de la aplicación es similar a la del ejemplo siguiente:

Azure Queue Storage client library v12 - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Cuando la aplicación se detiene antes de recibir mensajes, compruebe la cuenta de almacenamiento en Azure Portal. Compruebe que los mensajes están en la cola.

Presione la tecla Enter para recibir y eliminar los mensajes. Cuando se le solicite, presione de nuevo la tecla Enter para eliminar la cola y finalizar la demostración.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cola y a agregarle mensajes mediante código Java. Después aprendió a ver, recuperar y eliminar mensajes. Por último, ha aprendido a eliminar una cola de mensajes.

Para ver tutoriales, ejemplos, artículos de inicio rápido y otra documentación, visite: