Compartir a través de

biblioteca cliente de Azure Service Bus para JavaScript: versión 7.9.4

  • Artículo

Azure Service Bus es un servicio de mensajería en la nube altamente confiable de Microsoft.

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

  • Enviar mensajes a una cola o tema de Azure Service Bus
  • Recepción de mensajes de una cola o suscripción de Azure Service Bus
  • Create/Get/Delete/Update/List Queues/Topics/Subscriptions/Rules en un espacio de nombres de Azure Service Bus.

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

Vínculos principales:

NOTA: Si usa 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.

Introducción

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

Requisitos previos

Configuración de TypeScript

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

npm install @types/node

También debe habilitar compilerOptions.allowSyntheticDefaultImports en la tsconfig.json. Tenga en cuenta que si ha habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está habilitado de forma predeterminada. Consulte el 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 más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

Además de lo que se describe allí, esta biblioteca también necesita polyfills adicionales para los siguientes módulos integrados de NodeJS core para funcionar correctamente en los exploradores:

  • buffer
  • os
  • path
  • process

Unió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, agregue lo siguiente a la 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 acumulación

Si usa el empaquetador acumulativo, 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 el 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.

compatibilidad con React Native

De forma similar a los exploradores, React Native no admite algunas API de JavaScript usadas por esta biblioteca del 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 un cadena de conexión o mediante una credencial de Azure Active Directory.

Uso de un cadena de conexión

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

const { ServiceBusClient } = require("@azure/service-bus");

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

Puede encontrar más información 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 identidades de Azure.

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

const { ServiceBusClient } = require("@azure/service-bus");
const { DefaultAzureCredential } = require("@azure/identity");

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" para service-bus en lo siguiente para obtener el token adecuado:

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

Puede encontrar más información 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 usa para la comunicación de punto a punto.
  • Temas: en lugar de las colas, los temas son más adecuados para escenarios de publicación o suscripción. Se puede enviar un tema a , pero requiere una suscripción, de la que puede haber varios en paralelo, para consumir.
  • Suscripciones: mecanismo para consumir desde un tema. Cada suscripción es independiente y recibe una copia de cada mensaje enviado al tema. Las reglas y filtros se pueden usar para adaptar 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, debe estar familiarizado con los siguientes conceptos del SDK:

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

Ejemplos

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

Envío de mensajes

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

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 creada una instancia de una ServiceBusClient clase, puede obtener un ServiceBusReceiver mediante el método createReceiver .

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

Hay dos receiveModedisponibles.

  • "peekLock": en el modo peekLock, el receptor tiene un bloqueo en el mensaje durante la duración especificada en la cola.
  • "receiveAndDelete": en el modo receiveAndDelete, los mensajes se eliminan de Service Bus a medida que se reciben.

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

Puede usar este receptor de una de tres maneras de recibir mensajes:

Obtener una matriz de mensajes

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

const myMessages = await receiver.receiveMessages(10);

Suscribirse mediante un controlador de mensajes

Use el método subscribe para configurar controladores de mensajes y hacer que se ejecute siempre que necesite.

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

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

Usar iterador asincrónico

Usar getMessageIterator para obtener un iterador asincrónico a través de mensajes

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

Liquidar un mensaje

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

Para más información, lea Establecer mensajes recibidos.

Colas de mensajes fallidos

La cola de mensajes fallidos es una sub cola. Cada cola o suscripción tiene su propia cola de mensajes fallidos. Las colas de mensajes fallidos almacenan mensajes enviados explícitamente (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 sub cola de mensajes fallidos es similar a la creación de un receptor para una suscripción o cola:

// 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 muestran colas de mensajes fallidos más exhaustivamente:

Envío de mensajes mediante sesiones

El uso de sesiones requiere que cree una cola o una suscripción habilitadas para la sesión. Puede obtener más información sobre cómo configurar esta característica en el portal aquí.

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

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

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

Puede obtener más información sobre cómo funcionan las sesiones aquí.

Recibir mensajes de sesiones

El uso de sesiones requiere que cree una cola o una suscripción habilitadas para la sesión. Puede obtener más información sobre cómo configurar esta característica en el portal aquí.

A diferencia de las colas o suscripciones no habilitadas para sesión, solo un receptor puede leer desde una sesión en cualquier momento. Esto se aplica bloqueando una sesión, que se controla mediante 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, el receptor tiene acceso exclusivo a él.

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

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

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

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

  2. No especifique un identificador de sesión. En este caso, Service Bus encontrará 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 .SessionReceiver Si no se proporciona receiveMode en las opciones, el valor predeterminado es el modo "peekLock". También puede liquidar los mensajes recibidos en modo "peekLock".

Una vez creado el receptor, puede elegir entre tres maneras de recibir mensajes:

Puede obtener más información sobre cómo funcionan las sesiones aquí.

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 un cadena de conexión de Service Bus, 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 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í.

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

await serviceBusAdministrationClient.deleteQueue(queueName);

Solución de problemas

Estos son algunos pasos iniciales para empezar a diagnosticar problemas. Para 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 .

Registro

Puede establecer la siguiente variable de entorno para obtener los registros de depuración cuando se usa esta biblioteca.

  • Obtención de registros de depuración del SDK de Service Bus
export DEBUG=azure*
  • Obtención de registros de depuración desde el 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 mucha consola o espacio en 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 está interesado en 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 anteriormente.
  2. Ejecute el script de prueba de la siguiente manera:
  • Las instrucciones de registro del script de prueba van a out.log las instrucciones de registro y 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 redirigiendo stderr a stdout (&1) y luego redirige 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 hacia o desde colas, temas y suscripciones de Service Bus.

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.

Impresiones