Azure Service Bus client library for JavaScript - versión 7.10.0

Azure Service Bus es un servicio de mensajería en la nube de alta confianza de Microsoft.

Utilice la biblioteca @azure/service-bus cliente de la aplicación para

  • Envío de mensajes a una cola o un tema de Azure Service Bus
  • Recepción de mensajes de una cola o suscripción de Azure Service Bus
  • Crear/obtener/eliminar/actualizar/enumerar colas/temas/suscripciones/reglas en un espacio de nombres de Azure Service Bus.

Recursos para la @azure/service-bus versión 7:

Vínculos clave:

NOTA: Si utiliza la versión 1.1.10 o inferior y desea migrar a la versión más reciente de este paquete, consulte nuestra guía de migración para pasar de Service Bus V1 a Service Bus V7

Cómo empezar

Instalar el paquete

Instale la versión más reciente de la biblioteca cliente de Azure Service Bus mediante npm.

npm install @azure/service-bus

Entornos admitidos actualmente

Prerequisites

Configurar TypeScript

Los usuarios de TypeScript deben tener instaladas definiciones de tipo de nodo:

npm install @types/node

También debe habilitar compilerOptions.allowSyntheticDefaultImports en el tsconfig.json. Tenga en cuenta que si ha habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está habilitado de forma predeterminada. Consulte manual de opciones del compilador de TypeScript para obtener más información.

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

Además de lo que se describe allí, esta biblioteca también necesita polyfills adicionales para los siguientes módulos incorporados del núcleo de NodeJS para que funcione correctamente en los navegadores:

  • buffer
  • os
  • path
  • process

Agrupación con Webpack

Si usa Webpack v5, puede instalar las siguientes dependencias de desarrollo

  • npm install --save-dev os-browserify path-browserify

A continuación, añade lo siguiente a tu webpack.config.js

 const path = require("path");
+const webpack = require("webpack");

 module.exports = {
   entry: "./src/index.ts",
@@ -12,8 +13,21 @@ module.exports = {
       },
     ],
   },
+  plugins: [
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+    }),
+    new webpack.ProvidePlugin({
+      Buffer: ["buffer", "Buffer"],
+    }),
+  ],
   resolve: {
     extensions: [".ts", ".js"],
+    fallback: {
+      buffer: require.resolve("buffer/"),
+      os: require.resolve("os-browserify"),
+      path: require.resolve("path-browserify"),
+    },
   },

Agrupación con Rollup

Si usa Rollup Bundler, instale las siguientes dependencias de desarrollo

  • npm install --save-dev @rollup/plugin-commonjs @rollup/plugin-inject @rollup/plugin-node-resolve

A continuación, incluya lo siguiente en su rollup.config.js

+import nodeResolve from "@rollup/plugin-node-resolve";
+import cjs from "@rollup/plugin-commonjs";
+import shim from "rollup-plugin-shim";
+import inject from "@rollup/plugin-inject";

export default {
  // other configs
  plugins: [
+    shim({
+      fs: `export default {}`,
+      net: `export default {}`,
+      tls: `export default {}`,
+      path: `export default {}`,
+      dns: `export function resolve() { }`,
+    }),
+    nodeResolve({
+      mainFields: ["module", "browser"],
+      preferBuiltins: false,
+    }),
+    cjs(),
+    inject({
+      modules: {
+        Buffer: ["buffer", "Buffer"],
+        process: "process",
+      },
+      exclude: ["./**/package.json"],
+    }),
  ]
};

Consulte la documentación de su empaquetador favorito para obtener más información sobre el uso de polyfills.

Soporte nativo de React

Al igual que los navegadores, React Native no es compatible con algunas API de JavaScript utilizadas por esta biblioteca SDK, por lo que debe proporcionar polyfills para ellos. Consulte el ejemplo de mensajería React Native con Expo para obtener más detalles.

Autenticar el cliente

La interacción con Service Bus comienza con una instancia de la clase ServiceBusClient . Puede autenticarse en Service Bus mediante una cadena de conexión o mediante una credencial de Azure Active Directory.

Uso de una cadena de conexión

Este método toma la cadena de conexión a la instancia de Service Bus. Puede obtener la cadena de conexión desde Azure Portal.

import { ServiceBusClient } from "@azure/service-bus";

const serviceBusClient = new ServiceBusClient("<connectionString>");

Hay más información disponible sobre este constructor en la documentación de la API.

Uso de una credencial de Azure Active Directory

La autenticación con Azure Active Directory usa la biblioteca de identidad de Azure.

En el ejemplo siguiente se usa DefaultAzureCredential, uno de los muchos proveedores de credenciales disponibles en la @azure/identity biblioteca.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

NOTA: Si usa su propia implementación de la TokenCredential interfaz en AAD, establezca los "ámbitos" del bus de servicio en lo siguiente para obtener el token adecuado:

["https://servicebus.azure.net//user_impersonation"];

Hay más información disponible sobre este constructor en la documentación de la API

Conceptos clave

Una vez que haya inicializado un ServiceBusClient, puede interactuar con estos recursos dentro de un espacio de nombres de Service Bus:

  • Colas: Permite enviar y recibir mensajes. A menudo se utiliza para la comunicación punto a punto.
  • Temas: A diferencia de las colas, los temas son más adecuados para escenarios de publicación/suscripción. Un tema se puede enviar a, pero requiere una suscripción, de la cual puede haber varios en paralelo, para consumir.
  • Suscripciones: el mecanismo para consumir de un tema. Cada suscripción es independiente y recibe una copia de cada mensaje enviado al tema. Las reglas y los filtros se pueden usar para personalizar los mensajes que recibe una suscripción específica.

Para obtener más información sobre estos recursos, consulte ¿Qué es Azure Service Bus?.

Para interactuar con estos recursos, se debe estar familiarizado con los siguientes conceptos del SDK:

Tenga en cuenta que las colas, los temas y las suscripciones deben crearse antes de usar esta biblioteca.

Examples

En las secciones siguientes se proporcionan fragmentos de código que cubren algunas de las tareas comunes mediante Azure Service Bus

Enviar mensajes

Una vez que haya creado una instancia de una ServiceBusClient clase, puede obtener una ServiceBusSender utilizando el método createSender que puede usar para enviar mensajes.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const sender = serviceBusClient.createSender("my-queue");

const messages = [
  { body: "Albert Einstein" },
  { body: "Werner Heisenberg" },
  { body: "Marie Curie" },
  { body: "Steven Hawking" },
  { body: "Isaac Newton" },
  { body: "Niels Bohr" },
  { body: "Michael Faraday" },
  { body: "Galileo Galilei" },
  { body: "Johannes Kepler" },
  { body: "Nikolaus Kopernikus" },
];

// sending a single message
await sender.sendMessages(messages[0]);

// sending multiple messages in a single call
// this will fail if the messages cannot fit in a batch
await sender.sendMessages(messages);

// Sends multiple messages using one or more ServiceBusMessageBatch objects as required
let batch = await sender.createMessageBatch();

for (let i = 0; i < messages.length; i++) {
  const message = messages[i];
  if (!batch.tryAddMessage(message)) {
    // Send the current batch as it is full and create a new one
    await sender.sendMessages(batch);
    batch = await sender.createMessageBatch();

    if (!batch.tryAddMessage(messages[i])) {
      throw new Error("Message too big to fit in a batch");
    }
  }
}
// Send the batch
await sender.sendMessages(batch);

Recepción de mensajes

Una vez que haya creado una instancia de una ServiceBusClient clase, puede obtener una ServiceBusReceiver mediante el método createReceiver .

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

Hay dos receiveModes disponibles.

  • "peekLock": en el modo peekLock, el receptor tiene un bloqueo en el mensaje durante el tiempo especificado en la cola.
  • "receiveAndDelete": en el modo receiveAndDelete, los mensajes se eliminan del Bus de servicio a medida que se reciben.

Si receiveMode no se proporciona en las opciones, el valor predeterminado es el modo "peekLock". También puede liquidar los mensajes recibidos en el modo "peekLock".

Puede utilizar este receptor de una de las 3 formas de recibir mensajes:

Obtener una matriz de mensajes

Utilice la función receiveMessages , que devuelve una promesa que se resuelve en una matriz de mensajes.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

const myMessages = await receiver.receiveMessages(10);

Suscribirse mediante un controlador de mensajes

Use el método subscribe para configurar controladores de mensajes y tenerlo en ejecución todo el tiempo que necesite.

Cuando haya terminado, llame receiver.close() para dejar de recibir más mensajes.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

const myMessageHandler = async (message) => {
  // your code here
  console.log(`message.body: ${message.body}`);
};
const myErrorHandler = async (args) => {
  console.log(
    `Error occurred with ${args.entityPath} within ${args.fullyQualifiedNamespace}: `,
    args.error,
  );
};
receiver.subscribe({
  processMessage: myMessageHandler,
  processError: myErrorHandler,
});

Uso de un iterador asincrónico

Use getMessageIterator para obtener un iterador asincrónico sobre los mensajes

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

for await (const message of receiver.getMessageIterator()) {
  // your code here
}

Resolver un mensaje

Una vez que reciba un mensaje, puede llamar a completeMessage(), abandonMessage()deferMessage() o deadLetterMessage() al receptor en función de cómo desee liquidar el mensaje.

Para obtener más información, lea Liquidación de mensajes recibidos

Colas de mensajes fallidos

La cola de mensajes fallidos es una subcola. Cada cola o suscripción tiene su propia cola de mensajes fallidos. Las colas de mensajes fallidos almacenan mensajes que se han enviado explícitamente como mensajes fallidos (a través receiver.deadLetterMessage()de ) o mensajes que han superado su número máximo de entregas.

La creación de un receptor para una subcola de mensajes fallidos es similar a la creación de un receptor para una suscripción o cola:

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

// To receive from a queue's dead letter sub-queue
const deadLetterReceiverForQueue = serviceBusClient.createReceiver("queue", {
  subQueueType: "deadLetter",
});

// To receive from a subscription's dead letter sub-queue
const deadLetterReceiverForSubscription = serviceBusClient.createReceiver("topic", "subscription", {
  subQueueType: "deadLetter",
});

// Dead letter receivers work like any other receiver connected to a queue
// ex:
const messages = await deadLetterReceiverForQueue.receiveMessages(5);

for (const message of messages) {
  console.log(`Dead lettered message: ${message.body}`);
}

Ejemplos completos que demuestran las colas de mensajes fallidos de forma más exhaustiva:

Enviar mensajes mediante sesiones

El uso de sesiones requiere la creación de una cola o suscripción habilitada para la sesión. Puede obtener más información sobre cómo configurar esta función en el portal aquí.

Para enviar mensajes a una sesión, use el ServiceBusClient para crear un remitente usando createSender.

Al enviar el mensaje, establezca la sessionId propiedad en el mensaje para asegurarse de que el mensaje llegue a la sesión correcta.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const sender = serviceBusClient.createSender("my-session-queue");
await sender.sendMessages({
  body: "my-message-body",
  sessionId: "my-session",
});

Puedes leer más sobre cómo funcionan las sesiones aquí.

Recibir mensajes de sesiones

El uso de sesiones requiere la creación de una cola o suscripción habilitada para la sesión. Puede obtener más información sobre cómo configurar esta función en el portal aquí.

A diferencia de las colas o suscripciones no habilitadas para sesión, solo un único receptor puede leer una sesión en cualquier momento. Esto se aplica mediante el bloqueo de una sesión, que es controlada por Service Bus. Conceptualmente, esto es similar a cómo funciona el bloqueo de mensajes cuando se usa peekLock el modo: cuando un mensaje (o sesión) está bloqueado, su receptor tiene acceso exclusivo a él.

Para abrir y bloquear una sesión, use una instancia de ServiceBusClient para crear un SessionReceiver.

Hay dos formas de elegir qué sesión abrir:

  1. Especifique un sessionId, que bloquea una sesión con nombre.

    const receiver = await serviceBusClient.acceptSession("my-session-queue", "my-session");

  2. No especifique un ID de sesión. En este caso, Service Bus buscará la siguiente sesión disponible que aún no esté bloqueada.

    const receiver = await serviceBusClient.acceptNextSession("my-session-queue");

    Puede encontrar el nombre de la sesión a través de la sessionId propiedad en el SessionReceiverarchivo . Si receiveMode no se proporciona en las opciones, el valor predeterminado es el modo "peekLock". También puede liquidar los mensajes recibidos en el modo "peekLock".

Una vez creado el receptor, puede elegir entre 3 formas de recibir mensajes:

Puedes leer más sobre cómo funcionan las sesiones aquí.

Sesiones de mensajes de lista

Para descubrir qué sesiones tienen mensajes activos o estado de sesión en una cola o suscripción, utiliza listMessageSessions():

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

// List all sessions with active messages or session state in a queue
for await (const sessionId of serviceBusClient.listMessageSessions("my-session-queue")) {
  console.log("Session ID:", sessionId);
}

// List sessions in a subscription
for await (const sessionId of serviceBusClient.listMessageSessions("my-topic", "my-subscription")) {
  console.log("Session ID:", sessionId);
}

// List only sessions whose stored session state was set or updated in the last seven days
const sessionStateUpdatedAfter = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
for await (const sessionId of serviceBusClient.listMessageSessions("my-session-queue", {
  sessionStateUpdatedAfter,
})) {
  console.log("Recently updated session ID:", sessionId);
}

Administración de recursos de un espacio de nombres de Service Bus

ServiceBusAdministrationClient permite administrar un espacio de nombres con operaciones CRUD en las entidades (colas, temas y suscripciones) y en las reglas de una suscripción.

  • Admite la autenticación con una cadena de conexión de bus de servicio, así como con las credenciales de AAD de @azure/identity forma similar a .ServiceBusClient

Nota: Service Bus aún no admite la configuración de reglas de CORS para espacios de nombres, por lo que ServiceBusAdministrationClient no funcionará en el explorador sin deshabilitar la seguridad web. Para obtener más información, consulte aquí.

import { ServiceBusAdministrationClient } from "@azure/service-bus";

const queueName = "my-session-queue";

// Get the connection string from the portal
// OR
// use the token credential overload, provide the host name of your Service Bus instance and the AAD credentials from the @azure/identity library
const serviceBusAdministrationClient = new ServiceBusAdministrationClient("<connectionString>");

// Similarly, you can create topics and subscriptions as well.
const createQueueResponse = await serviceBusAdministrationClient.createQueue(queueName);
console.log("Created queue with name - ", createQueueResponse.name);

const queueRuntimeProperties =
  await serviceBusAdministrationClient.getQueueRuntimeProperties(queueName);
console.log(`Number of messages in the queue = ${queueRuntimeProperties.totalMessageCount}`);

// Topic runtime properties additionally report the total number of SQL and correlation filters
// across all of the topic's subscriptions. These counts are served by the 2024-05 service API
// version and later; on an older version they are `undefined`.
const topicName = "my-topic";
const subscriptionName = "my-subscription";
await serviceBusAdministrationClient.createTopic(topicName);
// A new subscription carries a default rule with a SQL TrueFilter. Adding a correlation rule
// gives the topic one of each, so the counts below aggregate across the subscription's rules.
await serviceBusAdministrationClient.createSubscription(topicName, subscriptionName);
await serviceBusAdministrationClient.createRule(
  topicName,
  subscriptionName,
  "my-correlation-rule",
  { correlationId: "my-correlation-id" },
);
const topicRuntimeProperties =
  await serviceBusAdministrationClient.getTopicRuntimeProperties(topicName);
console.log(`SQL filter count = ${topicRuntimeProperties.sqlFilterCount}`);
console.log(`Correlation filter count = ${topicRuntimeProperties.correlationFilterCount}`);

await serviceBusAdministrationClient.deleteTopic(topicName);
await serviceBusAdministrationClient.deleteQueue(queueName);

Troubleshooting

Estos son algunos pasos iniciales para comenzar a diagnosticar problemas. Para obtener más información, consulte la Guía de solución de problemas de Service Bus.

Dependencias de AMQP

La biblioteca de Service Bus depende de la biblioteca rhea-promise para administrar conexiones, enviar y recibir mensajes a través del protocolo AMQP .

Logging

Puede establecer la siguiente variable de entorno para obtener los registros de depuración al usar esta biblioteca.

  • Obtención de registros de depuración del SDK de Service Bus
export DEBUG=azure*
  • Obtener registros de depuración del SDK de Service Bus y la biblioteca de nivel de protocolo.
export DEBUG=azure*,rhea*
  • Si no está interesado en ver la transformación del mensaje (que consume mucho espacio en la consola/disco), puede establecer la variable de entorno de la DEBUG siguiente manera:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Si solo le interesan los errores, puede establecer la variable de entorno de la DEBUG siguiente manera:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Registro en un archivo

  1. Establezca la variable de DEBUG entorno como se muestra arriba
  2. Ejecute el script de prueba de la siguiente manera:
  • Las instrucciones de registro del script de prueba van a out.log y las instrucciones de registro del sdk van a debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Las instrucciones de registro del script de prueba y el SDK van al mismo archivo out.log redireccionando stderr a stdout (&1) y, a continuación, redirigen stdout a un archivo: 
    node your-test-script.js >out.log 2>&1
  • Las instrucciones de registro del script de prueba y el sdk van al mismo archivo out.log. 
      node your-test-script.js &> out.log

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca para enviar y recibir mensajes a/desde colas de Service Bus, temas y suscripciones.

Contributing

Si quieres contribuir a esta biblioteca, por favor lee la guía contribución para aprender más sobre cómo construir y probar el código.

  • Se actualizó por última vez el