Uso de Azure Queue Storage desde Node.js

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Información general

Esta guía le indicará cómo actuar en escenarios habituales usando Azure Queue Storage. Los ejemplos están escritos usando la API Node.js. Entre los escenarios descritos se incluyen la inserción, inspección, obtención y eliminación de mensajes de la cola. También aprenderá a crear y eliminar colas.

¿Qué es 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. 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. Queue Storage se usa normalmente para crear un trabajo pendiente del trabajo que se va a procesar de forma asincrónica.

Conceptos del servicio Queue

Azure Queue service contiene los siguientes componentes:

• 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. El tiempo máximo que un mensaje puede permanecer en la cola es 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.

• Formato de URL: las colas son direccionables mediante el siguiente formato de dirección URL: http://<storage account>.queue.core.windows.net/<queue>

  La siguiente dirección URL dirige a una cola del diagrama:

  http://myaccount.queue.core.windows.net/incoming-orders

Creación de una cuenta de Azure Storage

La forma más fácil de crear la primera cuenta de Azure Storage es a través de Azure Portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.

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.

Si no quiere crear una cuenta de almacenamiento en Azure en este momento, también puede utilizar el emulador de almacenamiento Azurite para ejecutar y probar el código en un entorno local. Para más información, consulte Uso del emulador de Azurite para desarrollo y pruebas locales de Azure Storage.

Creación de una aplicación Node.js

Para crear una aplicación de Node.js en blanco, consulte Creación de una aplicación web Node.js en Azure App Service, Creación e implementación de una aplicación Node.js en Azure Cloud Services con PowerShell o Visual Studio Code.

Configuración de la aplicación para acceder al almacenamiento

La biblioteca cliente de Azure Storage para JavaScript incluye un conjunto de bibliotecas útiles que se comunican con los servicios REST de almacenamiento.

Uso del Administrador de paquetes para Node (NPM) para obtener el paquete

1. Use una interfaz de línea de comandos, como PowerShell (Windows), Terminal (Mac) o Bash (Unix), y vaya a la carpeta donde ha creado la aplicación de ejemplo.

2. Escriba npm install @azure/storage-queue en la ventana de comandos.

3. Compruebe que se ha creado una carpeta node_modules. Dentro de dicha carpeta, encontrará el paquete @azure/storage-queue, que contiene la biblioteca cliente necesaria para acceder al almacenamiento.

Importación del paquete

Con el editor de código, agregue lo siguiente al principio del archivo de JavaScript en el que pretenda utilizar el las colas.

const { QueueClient, QueueServiceClient } = require("@azure/storage-queue");

Creación de una cola

En el código siguiente se obtiene el valor de una variable de entorno denominada AZURE_STORAGE_CONNECTION_STRING y se usa para crear un objeto QueueServiceClient. Este objeto se utiliza a continuación para crear un objeto QueueClient que permita trabajar con una cola específica.

// Retrieve the connection from an environment
// variable called AZURE_STORAGE_CONNECTION_STRING
const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "myqueue-" + Date.now().toString();

console.log("Creating queue: ", queueName);

// Instantiate a QueueServiceClient which will be used
// to create a QueueClient and to list all the queues
const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

// Get a QueueClient which will be used
// to create and manipulate a queue
const queueClient = queueServiceClient.getQueueClient(queueName);

// Create the queue
await queueClient.create();

Si la cola ya existe, se produce una excepción.

Cómo dar formato al mensaje

El tipo de mensaje es una cadena. Todos los mensajes se tratan como cadenas. Si necesita enviar un tipo de datos diferente, debe serializar ese tipo de datos en una cadena al enviar el mensaje y deserializar el formato de cadena al leer el mensaje.

Para convertir JSON en un formato de cadena y viceversa en Node.js, use las siguientes funciones auxiliares:

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

Cómo insertar un mensaje en una cola

Para agregar un mensaje a una cola, llame al método sendMessage.

messageText = "Hello, World";
console.log("Adding message to the queue: ", messageText);

// Add a message to the queue
await queueClient.sendMessage(messageText);

Inspección del mensaje siguiente

Puede inspeccionar el mensaje de la cola sin tener que quitarlo de esta, mediante una llamada al método peekMessages.

De forma predeterminada, peekMessages inspecciona un único mensaje. En el ejemplo siguiente se inspeccionan los cinco primeros mensajes de la cola. Si hay menos de cinco mensajes visibles, solo se devuelven los mensajes visibles.

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages: 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("Peeked message: ", peekedMessages.peekedMessageItems[i].messageText);
}

Si llama a peekMessages cuando no hay ningún mensaje en la cola, no se devolverá un error. Sin embargo, no se devolverá ningún mensaje.

Cambio del contenido de un mensaje en cola

En el ejemplo siguiente se actualiza el texto de un mensaje.

Cambie el contenido de un mensaje local en la cola mediante una llamada a updateMessage.

// Get the first message in the queue
var receivedMessages = await queueClient.receiveMessages();
const firstMessage = receivedMessages.receivedMessageItems[0];

// Update the received message
await queueClient.updateMessage(
    firstMessage.messageId,
    firstMessage.popReceipt,
    "This message has been updated"
);

Cómo quitar un mensaje de la cola

El proceso para quitar un mensaje de la cola consta de dos etapas:

1. Obtención del mensaje.

2. Eliminación del mensaje.

En el siguiente ejemplo se obtiene un mensaje y luego se elimina.

Para obtener un mensaje, llame al método receiveMessages. Esta llamada hace que los mensajes sean invisibles en la cola, así que ningún otro cliente puede procesarlos. Después de que la aplicación haya procesado un mensaje, llame a deleteMessage para eliminarlo de la cola.

// Get next message from the queue
receivedMessages = await queueClient.receiveMessages();
var message = receivedMessages.receivedMessageItems[0];

console.log("Dequeuing message: ", message.messageText);

await queueClient.deleteMessage(message.messageId, message.popReceipt);

De manera predeterminada, un mensaje solo está oculto durante 30 segundos. Después de 30 segundos, es visible para otros clientes. Puede especificar un valor diferente estableciendo options.visibilityTimeout al llamar a receiveMessages.

Si llama a receiveMessages cuando no hay ningún mensaje en la cola, no se devolverá un error. Sin embargo, no se devolverá ningún mensaje.

Opciones adicionales para quitar mensajes de la cola

Hay dos formas de personalizar la recuperación de mensajes de una cola:

• options.numberOfMessages: Recuperar un lote de mensajes (hasta 32).
• options.visibilityTimeout: Establecer un tiempo de espera de invisibilidad más largo o más corto.

El siguiente ejemplo utiliza el método receiveMessages para obtener cinco mensajes en una llamada. A continuación, procesa cada mensaje con un bucle for. También se establece el tiempo de espera de invisibilidad en cinco minutos para todos los mensajes que devuelve este método.

// Get up to 5 messages from the queue
const receivedMsgsResp = await queueClient.receiveMessages({ numberOfMessages: 5, visibilityTimeout: 5 * 60 });

for (i = 0; i < receivedMsgsResp.receivedMessageItems.length; i++)
{
    message = receivedMsgsResp.receivedMessageItems[i];
    console.log("Dequeuing message: ", message.messageText);
    await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

Obtención de la longitud de la cola

El método getProperties devuelve metadatos sobre la cola, junto con el número aproximado de mensajes que esperan en la cola.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Enumeración de las colas

Para recuperar una lista de colas, llame a QueueServiceClient.listQueues. Para recuperar una lista filtrada por un prefijo específico, establezca options.prefix en la llamada a listQueues.

for await (const item of queueServiceClient.listQueues()) {
  console.log("Queue: ", item.name);
}

Como eliminar una cola

Para eliminar una cola y todos los mensajes contenidos en ella, llame al método DeleteQueue en el objeto de cola QueueClient.

// Delete the queue
console.log("Deleting queue: ", queueClient.name);
await queueClient.delete();

Para borrar todos los mensajes de una cola sin eliminarla, llame a ClearMessages.

Sugerencia

Extraer del repositorio ejemplos de código de Azure Storage

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.

Pasos siguientes

Ahora que está familiarizado con los aspectos básicos de Queue Storage, utilice estos vínculos para obtener más información acerca de tareas de almacenamiento más complejas.

• Visite el blog del equipo de Azure Storage para conocer las novedades.
• Visite el repositorio Biblioteca cliente de Azure Storage para JavaScript en GitHub