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

Introducción a la biblioteca cliente de Azure Queue Storage 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.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (Maven) | Ejemplos

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

• Creación de una cola
• Adición de mensajes a una cola
• Leer los mensajes de una cola
• Eliminación de un mensaje de una cola
• la longitud de la cola
• mensajes de una cola
• Eliminación de mensajes de una cola
• Eliminación de una cola

Requisitos previos

• Kit de desarrollo de Java (JDK), versión 8 o posterior
• Apache Maven
• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento

Instalación

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

Creación del proyecto

Cree una aplicación Java llamada queues-quickstart.

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. Escriba el siguiente comando mvn para crear un proyecto "Hola, mundo" en Java.

   • PowerShell
   • Bash

   mvn archetype:generate `
       --define interactiveMode=n `
       --define groupId=com.queues.quickstart `
       --define artifactId=queues-quickstart `
       --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
   [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
   [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
   [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 recién creado.

   cd queues-quickstart
   

Instalación de los paquetes

Abra el archivo pom.xml en el editor de texto.

Agregue azure-sdk-bom para tomar una dependencia de la versión más reciente de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. El uso de azure-sdk-bom le impide especificar la versión de cada dependencia individual. Para más información sobre el BOM, consulte el archivo LÉAME de BOM del SDK de Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

A continuación, agregue los siguientes elementos de dependencia al grupo de dependencias. La dependencia de azure-identity es necesaria para las conexiones sin contraseña a los servicios de Azure.

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

Instalación del marco de la aplicación

Desde el directorio del proyecto:

1. Vaya al directorio /src/main/java/com/blobs/quickstart.
2. Abra el archivo App.java en el 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 quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Autentíquese en Azure

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código.

También puede autorizar directamente las solicitudes a los servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser meticulosos y no exponer nunca estos secretos en una ubicación que no sea segura. Cualquier persona que obtenga acceso a la contraseña o a la clave secreta puede autenticarse. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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:

• 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. Un mensaje puede permanecer en la cola durante un máximo 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.

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

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:

• Autorización del acceso y creación de un objeto de cliente
• Creación de una cola
• Adición de mensajes a una cola
• Leer los mensajes de una cola
• Eliminación de un mensaje de una cola
• la longitud de la cola
• Recepción y eliminación de mensajes de una cola
• Eliminación de una cola

az login

az login

Connect-AzAccount

import com.azure.identity.*;

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

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

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

System.out.println("Azure Queue Storage client library - 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");

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

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

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
QueueClient queueClient = new QueueClientBuilder()
        .connectionString(connectStr)
        .queueName(queueName)
        .buildClient();

Creación de una cola

Con el objeto QueueClient, llame al método create para crear la cola en la cuenta de almacenamiento.

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

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

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

la longitud de la cola

Puede obtener una estimación del número de mensajes existentes en una cola.

El método getProperties devuelve varios valores, incluido el número de mensajes que hay actualmente en una cola. 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. El método getApproximateMessageCount devuelve el último valor recuperado por la llamada a getProperties, sin llamar a Queue Storage.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

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());
    }
);

Al llamar al método receiveMessages, puede especificar opcionalmente un valor para maxMessages, que es el número de mensajes que se van a recuperar de la cola. El valor predeterminado es 1 mensaje y el máximo es 32 mensajes. También puede especificar un valor para visibilityTimeout, que oculta los mensajes de otras operaciones durante el período de tiempo de espera. El valor predeterminado es 30 segundos.

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 - 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:

• Para ver ejemplos de código relacionados que usan SDK de la versión 8 de Java en desuso, consulte Ejemplos de código que usan la versión 8 de Java.
• Para ver más aplicaciones de ejemplo de Azure Queue Storage, consulte los ejemplos de la biblioteca de Azure Queue Storage para Java.