Uso del almacenamiento de colas de Node.jsHow to use Queue storage from Node.js

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 le indicará cómo actuar en situaciones habituales usando el servicio Cola de Microsoft Azure.This guide shows you how to perform common scenarios using the Microsoft Azure Queue service. Los ejemplos están escritos usando la API Node.js.The samples are written using the Node.js API. 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.

¿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 Node.jsCreate a Node.js Application

Cree una aplicación Node.js vacía.Create a blank Node.js application. Para obtener instrucciones sobre cómo crear una aplicación Node.js, 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 Windows PowerShell o Visual Studio Code.For instructions creating a Node.js application, see Create a Node.js web app in Azure App Service, Build and deploy a Node.js application to an Azure Cloud Service using Windows PowerShell, or Visual Studio Code.

Configuración de la aplicación para obtener acceso al almacenamientoConfigure Your Application to Access Storage

Para usar el almacenamiento de Azure necesitará el SDK de Azure Storage para Node.js, que incluye un conjunto de útiles bibliotecas que se comunican con los servicios REST de almacenamiento.To use Azure storage, you need the Azure Storage SDK for Node.js, which includes a set of convenience libraries that communicate with the storage REST services.

Uso del Administrador de paquetes para Node (NPM) para obtener el paqueteUse Node Package Manager (NPM) to obtain the package

  1. Utilice 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.Use a command-line interface such as PowerShell (Windows,) Terminal (Mac,) or Bash (Unix), navigate to the folder where you created your sample application.

  2. Escriba npm install azure-storage en la ventana de comandos.Type npm install azure-storage in the command window. La salida del comando es similar al ejemplo siguiente.Output from the command is similar to the following example.

    azure-storage@0.5.0 node_modules\azure-storage
    +-- extend@1.2.1
    +-- xmlbuilder@0.4.3
    +-- mime@1.2.11
    +-- node-uuid@1.4.3
    +-- validator@3.22.2
    +-- underscore@1.4.4
    +-- readable-stream@1.0.33 (string_decoder@0.10.31, isarray@0.0.1, inherits@2.0.1, core-util-is@1.0.1)
    +-- xml2js@0.2.7 (sax@0.5.2)
    +-- request@2.57.0 (caseless@0.10.0, aws-sign2@0.5.0, forever-agent@0.6.1, stringstream@0.0.4, oauth-sign@0.8.0, tunnel-agent@0.4.1, isstream@0.1.2, json-stringify-safe@5.0.1, bl@0.9.4, combined-stream@1.0.5, qs@3.1.0, mime-types@2.0.14, form-data@0.2.0, http-signature@0.11.0, tough-cookie@2.0.0, hawk@2.3.1, har-validator@1.8.0)
    
  3. Puede ejecutar manualmente el comando ls para comprobar si se ha creado la carpeta node_modules.You can manually run the ls command to verify that a node_modules folder was created. Dentro de dicha carpeta, encontrará el paquete azure-storage , que contiene las bibliotecas necesarias para el acceso al almacenamiento.Inside that folder you will find the azure-storage package, which contains the libraries you need to access storage.

Importación del paqueteImport the package

Con el Bloc de notas u otro editor de texto, agregue lo siguiente en la parte superior del archivo server.js de la aplicación en la que pretenda usar el almacenamiento:Using Notepad or another text editor, add the following to the top the server.js file of the application where you intend to use storage:

var azure = require('azure-storage');

Configuración de una conexión de Azure StorageSetup an Azure Storage Connection

El módulo azure leerá las variables de entorno AZURE_STORAGE_ACCOUNT y AZURE_STORAGE_ACCESS_KEY o AZURE_STORAGE_CONNECTION_STRING para obtener información necesaria para conectarse a su cuenta de Azure Storage.The azure module will read the environment variables AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY, or AZURE_STORAGE_CONNECTION_STRING for information required to connect to your Azure storage account. Si no se configuran estas variables de entorno, debe especificar la información de la cuenta al llamar a createQueueService.If these environment variables are not set, you must specify the account information when calling createQueueService.

Instrucciones: Creación de una colaHow To: Create a Queue

El siguiente código crea un objeto QueueService , que le permite trabajar con colas.The following code creates a QueueService object, which enables you to work with queues.

var queueSvc = azure.createQueueService();

Utilice el método createQueueIfNotExists , que devuelve la cola especificada si ya existe o crea una nueva cola con el nombre especificado si todavía no existe.Use the createQueueIfNotExists method, which returns the specified queue if it already exists or creates a new queue with the specified name if it does not already exist.

queueSvc.createQueueIfNotExists('myqueue', function(error, results, response){
  if(!error){
    // Queue created or exists
  }
});

Si la cola se crea, result.created es verdadero.If the queue is created, result.created is true. Si la cola existe, result.created es falso.If the queue exists, result.created is false.

FiltrosFilters

Las operaciones de filtrado opcionales pueden aplicarse a las tareas realizadas mediante QueueService.Optional filtering operations can be applied to operations performed using QueueService. Las operaciones de filtrado pueden incluir registros, reintentos automáticos, etc. Los filtros son objetos que implementan un método con la firma:Filtering operations can include logging, automatically retrying, etc. Filters are objects that implement a method with the signature:

function handle (requestOptions, next)

Después de realizar el preprocesamiento en las opciones de solicitud, el método tiene que llamar a "next" pasando una devolución de llamada con la firma siguiente:After doing its preprocessing on the request options, the method needs to call "next" passing a callback with the following signature:

function (returnObject, finalCallback, next)

En esta devolución de llamada y después de procesar returnObject (la respuesta de la solicitud al servidor), la devolución de llamada tiene que invocar a next, si existe, para continuar procesando otros filtros, o bien simplemente invocar a finalCallback para finalizar la invocación del servicio.In this callback, and after processing the returnObject (the response from the request to the server), the callback needs to either invoke next if it exists to continue processing other filters or simply invoke finalCallback otherwise to end up the service invocation.

Se incluyen dos filtros que implementan la lógica de reintento con el SDK de Azure para Node.js: ExponentialRetryPolicyFilter y LinearRetryPolicyFilter.Two filters that implement retry logic are included with the Azure SDK for Node.js, ExponentialRetryPolicyFilter and LinearRetryPolicyFilter. Lo siguiente crea un objeto QueueService que usa ExponentialRetryPolicyFilter:The following creates a QueueService object that uses the ExponentialRetryPolicyFilter:

var retryOperations = new azure.ExponentialRetryPolicyFilter();
var queueSvc = azure.createQueueService().withFilter(retryOperations);

Instrucciones: Inserción de un mensaje en una colaHow To: Insert a Message into a Queue

Para insertar un mensaje en una cola, utilice el método createMessage para crear un nuevo mensaje y agregarlo a la cola.To insert a message into a queue, use the createMessage method to create a new message and add it to the queue.

queueSvc.createMessage('myqueue', "Hello world!", function(error, results, response){
  if(!error){
    // Message inserted
  }
});

Instrucciones: Inspección del 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 peekMessages .You can peek at the message in the front of a queue without removing it from the queue by calling the peekMessages method. De forma predeterminada, peekMessages inspecciona un único mensaje.By default, peekMessages peeks at a single message.

queueSvc.peekMessages('myqueue', function(error, results, response){
  if(!error){
    // Message text is in results[0].messageText
  }
});

El result contiene el mensaje.The result contains the message.

Nota

Si se usa peekMessages cuando no existen mensajes en la cola, no se devolverá un error, pero tampoco se devolverán mensajes.Using peekMessages when there are no messages in the queue will not return an error, however no messages will be returned.

Instrucciones: Extracción del siguiente mensaje de la colaHow To: Dequeue the Next Message

El procesamiento de un mensaje es un proceso que consta de dos etapas:Processing a message is a two-stage process:

  1. Extracción del mensaje de la cola.Dequeue the message.
  2. Eliminación del mensaje.Delete the message.

Para quitar un mensaje de la cola, use getMessages.To dequeue a message, use getMessages. De esta forma los mensajes se hacen invisible en la cola, así que ningún otro cliente puede procesarlos.This makes the messages invisible in the queue, so no other clients can process them. Después de que la aplicación haya procesado un mensaje, llame a deleteMessage para eliminarlo de la cola.Once your application has processed a message, call deleteMessage to delete it from the queue. En el siguiente ejemplo se obtiene un mensaje y luego se elimina:The following example gets a message, then deletes it:

queueSvc.getMessages('myqueue', function(error, results, response){
  if(!error){
    // Message text is in results[0].messageText
    var message = results[0];
    queueSvc.deleteMessage('myqueue', message.messageId, message.popReceipt, function(error, response){
      if(!error){
        //message deleted
      }
    });
  }
});

Nota

De manera predeterminada, un mensaje solo está oculto durante 30 segundos, después de lo cual es visible para otros clientes.By default, a message is only hidden for 30 seconds, after which it is visible to other clients. Puede especificar un valor diferente usando options.visibilityTimeout con getMessages.You can specify a different value by using options.visibilityTimeout with getMessages.

Nota

Si usa getMessages cuando no existen mensajes en la cola, no se devolverá un error, pero tampoco se devolverán mensajes.Using getMessages when there are no messages in the queue will not return an error, however no messages will be returned.

Instrucciones: Cambio del 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 mediante updateMessage.You can change the contents of a message in-place in the queue using updateMessage. En el ejemplo siguiente se actualiza el texto de un mensaje:The following example updates the text of a message:

queueSvc.getMessages('myqueue', function(error, getResults, getResponse){
  if(!error){
    // Got the message
    var message = getResults[0];
    queueSvc.updateMessage('myqueue', message.messageId, message.popReceipt, 10, {messageText: 'new text'}, function(error, updateResults, updateResponse){
      if(!error){
        // Message updated successfully
      }
    });
  }
});

Instrucciones: Opciones adicionales para quitar mensajes de la colaHow To: Additional 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:

  • options.numOfMessages - Recuperar un lote de mensajes (hasta 32).options.numOfMessages - Retrieve a batch of messages (up to 32.)
  • options.visibilityTimeout - Establecer un tiempo de espera de invisibilidad más largo o más corto.options.visibilityTimeout - Set a longer or shorter invisibility timeout.

En el siguiente ejemplo se usa el método getMessages para obtener 15 mensajes en una llamada.The following example uses the getMessages method to get 15 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 se establece el tiempo de espera de invisibilidad en cinco minutos para todos los mensajes que devuelve este método.It also sets the invisibility timeout to five minutes for all messages returned by this method.

queueSvc.getMessages('myqueue', {numOfMessages: 15, visibilityTimeout: 5 * 60}, function(error, results, getResponse){
  if(!error){
    // Messages retrieved
    for(var index in result){
      // text is available in result[index].messageText
      var message = results[index];
      queueSvc.deleteMessage(queueName, message.messageId, message.popReceipt, function(error, deleteResponse){
        if(!error){
          // Message deleted
        }
      });
    }
  }
});

Instrucciones: Obtención de la longitud de la colaHow To: Get the Queue Length

El método getQueueMetadata devuelve metadatos sobre la cola, junto con el número aproximado de mensajes que esperan en la cola.The getQueueMetadata returns metadata about the queue, including the approximate number of messages waiting in the queue.

queueSvc.getQueueMetadata('myqueue', function(error, results, response){
  if(!error){
    // Queue length is available in results.approximateMessageCount
  }
});

Instrucciones: Enumeración de las colasHow To: List Queues

Para recuperar una lista de colas, use listQueuesSegmented.To retrieve a list of queues, use listQueuesSegmented. Para recuperar una lista filtrada por un prefijo determinado, use listQueuesSegmentedWithPrefix.To retrieve a list filtered by a specific prefix, use listQueuesSegmentedWithPrefix.

queueSvc.listQueuesSegmented(null, function(error, results, response){
  if(!error){
    // results.entries contains the list of queues
  }
});

Si no se pueden devolver todas las colas, result.continuationToken se puede usar como el primer parámetro de listQueuesSegmented o el segundo parámetro de listQueuesSegmentedWithPrefix para recuperar más resultados.If all queues cannot be returned, result.continuationToken can be used as the first parameter of listQueuesSegmented or the second parameter of listQueuesSegmentedWithPrefix to retrieve more results.

Instrucciones: Eliminación de una colaHow To: Delete a Queue

Para eliminar una cola y todos los mensajes contenidos en ella, llame al método deleteQueue en el objeto de cola.To delete a queue and all the messages contained in it, call the deleteQueue method on the queue object.

queueSvc.deleteQueue(queueName, function(error, response){
  if(!error){
    // Queue has been deleted
  }
});

Para borrar todos los mensajes de una cola sin eliminarla, use clearMessages.To clear all messages from a queue without deleting it, use clearMessages.

Procedimientos para: Trabajo con firmas de acceso compartidoHow to: Work with Shared Access Signatures

Las firmas de acceso compartido (SAS) constituyen una manera segura de ofrecer acceso granular a las colas sin proporcionar el nombre o las claves de su cuenta de almacenamiento.Shared Access Signatures (SAS) are a secure way to provide granular access to queues without providing your storage account name or keys. Las SAS se usan con frecuencia para proporcionar acceso limitado a sus colas, por ejemplo, para permitir que una aplicación móvil envíe mensajes.SAS are often used to provide limited access to your queues, such as allowing a mobile app to submit messages.

Una aplicación de confianza, como un servicio basado en la nube, genera una SAS mediante el valor de generateSharedAccessSignature del elemento QueueService, y lo proporciona a una aplicación en la que no se confía o en la que se confía parcialmente.A trusted application such as a cloud-based service generates a SAS using the generateSharedAccessSignature of the QueueService, and provides it to an untrusted or semi-trusted application. Por ejemplo, una aplicación móvil.For example, a mobile app. La SAS se genera usando una directiva que describe las fechas de inicio y de finalización durante las cuales la SAS es válida, junto con el nivel de acceso otorgado al titular de la SAS.The SAS is generated using a policy, which describes the start and end dates during which the SAS is valid, as well as the access level granted to the SAS holder.

En el siguiente ejemplo se genera una nueva directiva de acceso compartido que permitirá al titular de la SAS agregar mensajes a la cola, y que expira 100 minutos después de la hora en que se crea.The following example generates a new shared access policy that will allow the SAS holder to add messages to the queue, and expires 100 minutes after the time it is created.

var startDate = new Date();
var expiryDate = new Date(startDate);
expiryDate.setMinutes(startDate.getMinutes() + 100);
startDate.setMinutes(startDate.getMinutes() - 100);

var sharedAccessPolicy = {
  AccessPolicy: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.ADD,
    Start: startDate,
    Expiry: expiryDate
  }
};

var queueSAS = queueSvc.generateSharedAccessSignature('myqueue', sharedAccessPolicy);
var host = queueSvc.host;

Tenga en cuenta que también se debe proporcionar la información del host, puesto que es necesaria cuando el titular de la SAS intenta acceder a la cola.Note that the host information must be provided also, as it is required when the SAS holder attempts to access the queue.

La aplicación cliente usa entonces la SAS con QueueServiceWithSAS para realizar operaciones contra la cola.The client application then uses the SAS with QueueServiceWithSAS to perform operations against the queue. En el siguiente ejemplo se realiza la conexión a la cola y se crea un mensaje.The following example connects to the queue and creates a message.

var sharedQueueService = azure.createQueueServiceWithSas(host, queueSAS);
sharedQueueService.createMessage('myqueue', 'Hello world from SAS!', function(error, result, response){
  if(!error){
    //message added
  }
});

Dado que la SAS se generó solo con acceso para agregar, si se realizara un intento para leer, actualizar o eliminar mensajes, se devolvería un error.Since the SAS was generated with add access, if an attempt were made to read, update or delete messages, an error would be returned.

Listas de control de accesoAccess control lists

Se puede usar una lista de control de acceso (ACL) para definir la directiva de acceso para una SAS.You can also use an Access Control List (ACL) to set the access policy for a SAS. Esto es útil si desea permitir que varios clientes accedan a la cola, pero cada uno con directivas de acceso diferentes.This is useful if you wish to allow multiple clients to access the queue, but provide different access policies for each client.

Una ACL se implementa mediante el uso de un conjunto de directivas de acceso, con un Id. asociado a cada directiva.An ACL is implemented using an array of access policies, with an ID associated with each policy. En los siguientes ejemplos se definen dos directivas; una para "user1" y otra para "user2":The following example defines two policies; one for 'user1' and one for 'user2':

var sharedAccessPolicy = {
  user1: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.PROCESS,
    Start: startDate,
    Expiry: expiryDate
  },
  user2: {
    Permissions: azure.QueueUtilities.SharedAccessPermissions.ADD,
    Start: startDate,
    Expiry: expiryDate
  }
};

En el siguiente ejemplo se obtiene la ACL actual para myqueue y luego se agregan las nuevas directivas mediante setQueueAcl.The following example gets the current ACL for myqueue, then adds the new policies using setQueueAcl. Este enfoque permite lo siguiente:This approach allows:

var extend = require('extend');
queueSvc.getQueueAcl('myqueue', function(error, result, response) {
  if(!error){
    var newSignedIdentifiers = extend(true, result.signedIdentifiers, sharedAccessPolicy);
    queueSvc.setQueueAcl('myqueue', newSignedIdentifiers, function(error, result, response){
      if(!error){
        // ACL set
      }
    });
  }
});

Después de establecer una ACL, puede crear luego una SAS basada en el Id. de una directiva.Once the ACL has been set, you can then create a SAS based on the ID for a policy. En el siguiente ejemplo se crea una nueva SAS para 'user2':The following example creates a new SAS for 'user2':

queueSAS = queueSvc.generateSharedAccessSignature('myqueue', { Id: 'user2' });

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.

Creación de una aplicación web de Node.js en Azure App ServiceCreate a Node.js web app in Azure App Service

Creación e implementación de una aplicación Node.js en un servicio en la nube de AzureBuild and deploy a Node.js application to an Azure Cloud Service