Biblioteca cliente de Azure Service Bus para JavaScript: versión 7.9.5

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

• Envío de mensajes a una cola o tema de Azure Service Bus
• Recepción de mensajes de una cola o suscripción de Azure Service Bus
• Cree,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:

• Código fuente
• Paquete (npm)
• Documentación de referencia de API
• Documentación del producto
• Muestras
• Problemas al iniciar sesión en una aplicación que no es de la galería configurada para inicio de sesión único federado

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

• Versiones de LTS de Node.js

Requisitos previos

• Una suscripción de Azure
• Un espacio de nombres de Service Bus

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 la tsconfig.json. Tenga en cuenta que si ha habilitado , allowSyntheticDefaultImports está habilitado compilerOptions.esModuleInteropde 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 empaquetador. 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 polirrellenes adicionales para los siguientes módulos integrados principales de NodeJS para funcionar correctamente en los exploradores:

• 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, agregue lo siguiente al 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 polirrellenes para ellos. Consulte el ejemplo de Messaging 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 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 y 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 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:

• Envíe mensajes a una cola o tema mediante un ServiceBusSender objeto creado mediante ServiceBusClient.createSender().
• Recibir mensajes, de una cola o de una suscripción, mediante un ServiceBusReceiver creado mediante ServiceBusClient.createReceiver().
• Recibir mensajes, desde colas o suscripciones habilitadas para la sesión, mediante un ServiceBusSessionReceiver creado mediante ServiceBusClient.acceptSession() o ServiceBusClient.acceptNextSession().

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

Ejemplos

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

• Envío de mensajes
• Recepción de mensajes
• Liquidar un mensaje
• Colas de mensajes fallidos
• Envío de mensajes mediante sesiones
• Recepción de mensajes de sesiones
• Administración de recursos de un espacio de nombres de Service Bus
• Ejemplos adicionales

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 que haya creado una instancia de una ServiceBusClient clase, puede obtener mediante ServiceBusReceiver 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 las 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 sea necesario.

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 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 escrito explícitamente con mensajes fallidos (a través de receiver.deadLetterMessage()) 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 las colas de mensajes fallidos más exhaustivamente:

• Uso de receiver.deadLetterMessage() para enviar mensajes explícitamente a la sub cola de mensajes fallidos
• Recepción de mensajes de la sub cola de mensajes fallidos

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 ServiceBusClient para 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í.

Recepción de 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 la sesión, solo un único receptor puede leer desde una sesión en cualquier momento. Esto se aplica mediante el bloqueo de una sesión, que se controla mediante Service Bus. Conceptualmente, esto es similar a cómo funciona el bloqueo de mensajes al usar 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 sessionId, 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 formas de recibir mensajes:

• Obtener una matriz de mensajes
• Suscribirse mediante un controlador de mensajes
• Usar iterador asincrónico

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

• Ejemplo de referencia: administrationClient.ts

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 de mensajes (que consume gran cantidad de espacio en disco o consola), puede establecer la DEBUG variable de entorno de la siguiente manera:

export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer

• Si solo está interesado en errores, puede establecer la DEBUG variable de entorno de la 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 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 redirigiendo 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 hacia y 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.