Biblioteca cliente de cola de Azure Storage para JavaScript: versión 12.17.0
La cola de Azure Storage proporciona mensajería en la nube entre los componentes de la aplicación. A la hora de diseñar aplicaciones para escala, los componentes de las mismas suelen desacoplarse para poder escalarlos de forma independiente. El almacenamiento en cola ofrece mensajería asincrónica para la comunicación entre los componentes de las aplicaciones, independientemente de si se ejecutan en la nube, en el escritorio, en un servidor local o en un dispositivo móvil. Además, este tipo de almacenamiento admite la administración de tareas asincrónicas y la creación de flujos de trabajo de procesos.
Este proyecto proporciona una biblioteca cliente en JavaScript que facilita el consumo del servicio De cola de Azure Storage.
Use las bibliotecas cliente de este paquete para:
- Obtener o establecer propiedades de Queue Service
- Create/List/Delete Queues
- Enviar,recibir/Vistazo/Borrar/actualizar/eliminar mensajes de cola
Vínculos principales:
- Código fuente
- Paquete (npm)
- Documentación de referencia de API
- Documentación del producto
- Muestras
- API REST de cola de Azure Storage
Introducción
Entornos admitidos actualmente
- Versiones de LTS de Node.js
- Versiones más recientes de Safari, Chrome, Edge y Firefox.
Para más información, consulte la directiva de compatibilidad.
Requisitos previos
Instalar el paquete
La manera preferida de instalar la biblioteca cliente de cola de Azure Storage para JavaScript es usar el administrador de paquetes npm. Escriba lo siguiente en una ventana de terminal:
npm install @azure/storage-queue
Autenticar el cliente
Azure Storage admite varias maneras de autenticarse. Para interactuar con el servicio Azure Queue Storage, deberá crear una instancia de un cliente QueueServiceClient
de Storage, o QueueClient
por ejemplo. Consulte ejemplos para crear para QueueServiceClient
obtener más información sobre la autenticación.
Azure Active Directory
El servicio Azure Queue Storage admite el uso de Azure Active Directory para autenticar las solicitudes en sus API. El paquete @azure/identity
proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. Consulte el archivo Léame para @azure/identity
obtener más detalles y ejemplos para empezar.
Compatibilidad
Esta biblioteca es compatible con Node.js y exploradores, y se valida con las versiones de Node.js LTS (>=8.16.0) y las versiones más recientes de Chrome, Firefox y Edge.
Trabajos web
Esta biblioteca requiere que determinados objetos DOM estén disponibles globalmente cuando se usan en el explorador, que los trabajadores web no están disponibles de forma predeterminada. Tendrá que rellenarlos para que esta biblioteca funcione en los trabajos web.
Para más información, consulte nuestra documentación para usar Azure SDK para JS en Web Workers.
Esta biblioteca depende de las siguientes API DOM que necesitan polirrellenes externos cargados cuando se usan en trabajos web:
Diferencias entre Node.js y exploradores
Hay diferencias entre Node.js y el tiempo de ejecución de exploradores. Al empezar a trabajar con esta biblioteca, preste atención a las API o clases marcadas con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSER" (SOLO DISPONIBLE EN EXPLORADORES).
Las siguientes características, interfaces, clases o funciones solo están disponibles en Node.js
- Autorización de clave compartida basada en el nombre de cuenta y la clave de cuenta
StorageSharedKeyCredential
- Generación de firmas de acceso compartido (SAS)
generateAccountSASQueryParameters()
generateQueueSASQueryParameters()
Paquete de JavaScript
Para usar esta biblioteca cliente en el explorador, primero debe usar un empaquetador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.
CORS
Debe configurar reglas de uso compartido de recursos entre orígenes (CORS) para la cuenta de almacenamiento si necesita desarrollar para exploradores. Vaya a Azure Portal y Explorador de Azure Storage, busque la cuenta de almacenamiento, cree nuevas reglas de CORS para blob/queue/file/table service(s).
Por ejemplo, puede crear la siguiente configuración de CORS para la depuración. Pero personalice cuidadosamente la configuración según sus requisitos en el entorno de producción.
- Orígenes permitidos: *
- Verbos permitidos: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
- Encabezados permitidos: *
- Encabezados expuestos: *
- Antigüedad máxima (segundos): 86400
Conceptos clave
Una cola es un almacén de datos dentro de una cuenta de Azure Storage Queue Service para enviar o recibir mensajes entre clientes conectados.
Los tipos de datos clave de nuestra biblioteca relacionados con estos servicios son:
QueueServiceClient
representa una conexión (a través de una dirección URL) a una cuenta de almacenamiento determinada en el servicio De cola de Azure Storage y proporciona API para manipular sus colas. Se autentica en el servicio y se puede usar para crearQueueClient
objetos, así como crear, eliminar y enumerar colas del servicio.QueueClient
representa una sola cola en la cuenta de almacenamiento. Se puede usar para manipular los mensajes de la cola, por ejemplo, para enviar, recibir y ver mensajes en la cola.
Ejemplos
Importación del paquete
Para usar los clientes, importe el paquete en el archivo:
const AzureStorageQueue = require("@azure/storage-queue");
Como alternativa, importe de forma selectiva solo los tipos que necesita:
const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");
Creación del cliente del servicio de cola
QueueServiceClient
requiere una dirección URL para el servicio de cola y una credencial de acceso. También acepta algunas opciones de configuración en el options
parámetro .
con DefaultAzureCredential
desde @azure/identity
el paquete
Forma recomendada de crear una instancia de un QueueServiceClient
Configuración: Referencia: autorización del acceso a blobs y colas con Azure Active Directory desde una aplicación cliente: /azure/storage/common/storage-auth-aad-app
Registro de una nueva aplicación de AAD y concesión de permisos para acceder a Azure Storage en nombre del usuario que ha iniciado sesión
- Registro de una nueva aplicación en Azure Active Directory (en azure-portal): /azure/active-directory/develop/quickstart-register-app
- En la
API permissions
sección, seleccioneAdd a permission
y elijaMicrosoft APIs
. - Seleccione
Azure Storage
y active la casilla situada junto a y, auser_impersonation
continuación, haga clic enAdd permissions
. Esto permitiría que la aplicación acceda a Azure Storage en nombre del usuario que ha iniciado sesión.
Concesión de acceso a los datos de cola de Azure Storage con RBAC en Azure Portal
- Roles de RBAC para blobs y colas: /azure/storage/common/storage-auth-aad-rbac-portal.
- En Azure Portal, vaya a la cuenta de almacenamiento y asigne el rol Colaborador de datos de cola de Storage a la aplicación de AAD registrada desde
Access control (IAM)
la pestaña (en la barra de navegación del lado izquierdo de la cuenta de almacenamiento en Azure-Portal).
Configuración del entorno para el ejemplo
- En la página de información general de la aplicación de AAD, anote y
CLIENT ID
TENANT ID
. En la pestaña "Certificados & secretos", cree un secreto y anotelo. - Asegúrese de que tiene
AZURE_TENANT_ID
,AZURE_CLIENT_ID
,AZURE_CLIENT_SECRET
como variables de entorno para ejecutar correctamente el ejemplo (puede aprovechar process.env).
- En la página de información general de la aplicación de AAD, anote y
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
[Nota: los pasos anteriores solo son para Node.js]
uso de cadena de conexión
Como alternativa, puede crear una QueueServiceClient
instancia de mediante el fromConnectionString()
método estático con el cadena de conexión completo como argumento. (El cadena de conexión se puede obtener en Azure Portal). [SOLO DISPONIBLE EN NODE.JS RUNTIME]
const { QueueServiceClient } = require("@azure/storage-queue");
const connStr = "<connection string>";
const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);
Con StorageSharedKeyCredential
Como alternativa, cree una instancia QueueServiceClient
de con un StorageSharedKeyCredential
mediante el paso de account-name y account-key como argumentos. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal). [SOLO DISPONIBLE EN NODE.JS RUNTIME]
const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");
// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
sharedKeyCredential,
{
retryOptions: { maxTries: 4 }, // Retry options
telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry string
}
);
con token de SAS
Además, puede crear QueueServiceClient
una instancia de con una firma de acceso compartido (SAS). Puede obtener el token de SAS desde Azure Portal o generar uno mediante generateAccountSASQueryParameters()
.
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net${sas}`
);
Enumerar colas en esta cuenta
Use QueueServiceClient.listQueues()
la función para iterar las colas, con la nueva for-await-of
sintaxis:
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
async function main() {
let iter1 = queueServiceClient.listQueues();
let i = 1;
for await (const item of iter1) {
console.log(`Queue${i}: ${item.name}`);
i++;
}
}
main();
Como alternativa, sin for-await-of
:
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
async function main() {
let iter2 = queueServiceClient.listQueues();
let i = 1;
let item = await iter2.next();
while (!item.done) {
console.log(`Queue ${i++}: ${item.value.name}`);
item = await iter2.next();
}
}
main();
Para obtener un ejemplo completo sobre las colas de iteración, consulte samples/v12/typescript/listQueues.ts.
Creación de una cola
Use QueueServiceClient.getQueueClient()
la función para crear una nueva cola.
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
const queueName = "<valid queue name>";
async function main() {
const queueClient = queueServiceClient.getQueueClient(queueName);
const createQueueResponse = await queueClient.create();
console.log(
`Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
);
}
main();
Enviar un mensaje a la cola
Use sendMessage()
para agregar un mensaje a la cola:
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
const queueName = "<valid queue name>";
async function main() {
const queueClient = queueServiceClient.getQueueClient(queueName);
// Send a message into the queue using the sendMessage method.
const sendMessageResponse = await queueClient.sendMessage("Hello World!");
console.log(
`Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`
);
}
main();
Consulta un mensaje
QueueClient.peekMessages()
permite examinar uno o varios mensajes delante de la cola. Esta llamada no impide que otro código acceda a mensajes inspeccionados.
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
const queueName = "<valid queue name>";
async function main() {
const queueClient = queueServiceClient.getQueueClient(queueName);
const peekMessagesResponse = await queueClient.peekMessages();
console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}
main();
Procesamiento de un mensaje
Los mensajes se procesan en dos pasos.
- En primer lugar, llame a
queueClient.receiveMessages()
. Esto hace que los mensajes no se vean en otros mensajes de lectura de código de esta cola durante un período predeterminado de 30 segundos. - Cuando se realiza el procesamiento de un mensaje, llame a
queueClient.deleteMessage()
con el mensajepopReceipt
.
Si el código no puede procesar un mensaje debido a un error de hardware o software, este proceso de dos pasos garantiza que otra instancia del código pueda obtener el mismo mensaje e intentarlo de nuevo.
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
const queueName = "<valid queue name>";
async function main() {
const queueClient = queueServiceClient.getQueueClient(queueName);
const response = await queueClient.receiveMessages();
if (response.receivedMessageItems.length == 1) {
const receivedMessageItem = response.receivedMessageItems[0];
console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
const deleteMessageResponse = await queueClient.deleteMessage(
receivedMessageItem.messageId,
receivedMessageItem.popReceipt
);
console.log(
`Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`
);
}
}
main();
Eliminación de una cola
const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account>";
const credential = new DefaultAzureCredential();
const queueServiceClient = new QueueServiceClient(
`https://${account}.queue.core.windows.net`,
credential
);
const queueName = "<valid queue name>";
async function main() {
const queueClient = queueServiceClient.getQueueClient(queueName);
const deleteQueueResponse = await queueClient.delete();
console.log(
`Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
);
}
main();
Un ejemplo completo de escenarios simples QueueServiceClient
se encuentra en samples/v12/typescript/src/queueClient.ts.
Solución de problemas
La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL
en info
. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel
en @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Pasos siguientes
Más ejemplos de código
Contribuciones
Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.
Consulte también la guía específica del almacenamiento para obtener información adicional sobre cómo configurar el entorno de prueba para las bibliotecas de almacenamiento.
Azure SDK for JavaScript
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de