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 un gran número 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 la API de referencia | Código | Paquete (Maven) | Ejemplos

Use la biblioteca cliente de Azure Queue Storage para Java para:

• Creación de una cola
• Agregar mensajes a una cola
• Echar un vistazo a los mensajes en una cola
• Actualiza un mensaje en una cola
• Obtén la longitud de la cola
• mensajes de una cola
• Eliminación de mensajes de una cola
• Eliminación de una cola

Prerrequisitos

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

Configuración

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

Creación del proyecto

Cree una aplicación java denominada queues-quickstart.

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

   • 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 depender de la versión más reciente de la biblioteca. En el fragmento de código siguiente, reemplace el {bom_version_to_target} marcador de posición por el número de versión. El uso de azure-sdk-bom le impide tener que especificar la versión de cada dependencia individual. Para más información sobre el BOM, consulte el README 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/queues/quickstart .
2. Abra el archivo App.java en el editor.
3. Eliminar la System.out.println("Hello, world"); instrucción
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

Las solicitudes de aplicación a la mayoría de los servicios de Azure deben estar autorizadas. El uso de la DefaultAzureCredential clase proporcionada por la biblioteca cliente de Identidad de Azure es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código.

También puede autorizar solicitudes a servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales directamente. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca estos secretos en una ubicación no segura. Cualquier persona que obtenga acceso a la contraseña o la clave secreta puede autenticarse. DefaultAzureCredential ofrece una administración mejorada y ventajas de seguridad sobre 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 un gran número de mensajes. Un mensaje de cola puede tener un tamaño de 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 usan normalmente para crear un trabajo pendiente para 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 la cuenta de almacenamiento.
• Cola: una cola contiene un conjunto de mensajes. Todos los mensajes deben estar en una cola. Tenga en cuenta que el nombre de la cola debe estar en minúsculas. Para más información sobre cómo nombrar colas, consulte Nombramiento de 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. Para la versión 2017-07-29 o posterior, el período máximo de vida puede ser cualquier número positivo o -1 que indica que el mensaje no expira. Si se omite este parámetro, el período de vida predeterminado es de siete días.

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

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

• QueueClientBuilder: la QueueClientBuilder clase configura y crea instancias de un QueueClient objeto .
• QueueServiceClient QueueServiceClient: permite administrar todas las colas de la cuenta de almacenamiento.
• QueueClient: la QueueClient clase 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
• Agregar mensajes a una cola
• Echar un vistazo a los mensajes en una cola
• Actualizar un mensaje en una cola
• Obtenga la longitud de la cola
• Recibir y eliminar mensajes de una cola
• Eliminar 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 main método :

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

// Create the queue
queueClient.create();

Agregar mensajes a una cola

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

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

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

Echar un vistazo a los mensajes en 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 desde la parte frontal de la cola, pero no modifica la visibilidad del mensaje.

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

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

Actualiza un mensaje en una cola

Actualice el contenido de un mensaje llamando al updateMessage método . Este método puede cambiar el tiempo de espera y el contenido de visibilidad de un mensaje. El contenido del mensaje debe ser una cadena codificada UTF-8 con un tamaño de hasta 64 KB. 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 el recibo de confirmación identifican qué mensaje debe actualizarse.

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

Obtén la longitud de la cola

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

El getProperties método devuelve varios valores, incluido el número de mensajes que se encuentran actualmente en una cola. El recuento solo es aproximado porque los mensajes se pueden agregar o quitar después de la 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 agregados anteriormente llamando al receiveMessages método . El código de ejemplo también elimina los mensajes de la cola después de recibirlos y procesarlos. 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 han sido eliminados explícitamente eventualmente se vuelven visibles en la cola una vez más, ofreciendo otra oportunidad para procesarlos.

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

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 receiveMessages método , 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 código siguiente limpia los recursos que creó la aplicación eliminando la cola usando el método Delete.

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

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 enumera los mensajes de la cola y, a continuación, los recupera y los elimina, antes de eliminar la cola finalmente.

En la ventana de la consola, vaya al directorio de la aplicación y, a continuación, compile y ejecute la aplicación.

mvn compile

A continuación, compile el paquete.

mvn package

Use el siguiente mvn comando 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 al 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 pausa antes de recibir mensajes, compruebe la cuenta de almacenamiento en Azure Portal. Compruebe que los mensajes están en la cola.

Presione la Enter tecla para recibir y eliminar los mensajes. Cuando se le solicite, vuelva a presionar la Enter tecla para eliminar la cola y finalizar la demostración.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cola y a agregar mensajes a ella mediante código Java. A continuación, has aprendido a echar un vistazo, recuperar y eliminar mensajes. Por último, ha aprendido a eliminar una cola de mensajes.

Para ver tutoriales, ejemplos, inicios rápidos y otra documentación, visite:

• Para ver ejemplos de código relacionados con sdk de Java versión 8 en desuso, consulte Ejemplos de código con la versión 8 de Java.
• Para más aplicaciones de ejemplo de Azure Queue Storage, consulte Biblioteca cliente de Azure Queue Storage para Java: ejemplos.