Azure Service Bus client library for JavaScript - version 7.10.0

Azure Service Bus est un service de messagerie cloud hautement fiable de Microsoft.

Utilisez la bibliothèque @azure/service-bus cliente dans votre application pour

  • Envoyer des messages à une file d’attente ou à une rubrique Azure Service Bus
  • Recevoir des messages à partir d’une file d’attente ou d’un abonnement Azure Service Bus
  • Créez/Obtenez/Supprimez/Mettez à jour/Listez les files d’attente/Rubriques/Abonnements/Règles dans un espace de noms Azure Service Bus.

Ressources pour @azure/service-bus la version 7 :

Liens clés :

REMARQUE : Si vous utilisez la version 1.1.10 ou une version antérieure et que vous souhaitez migrer vers la dernière version de ce package, consultez notre guide de migration pour passer de Service Bus V1 à Service Bus V7

Premiers pas

Installer le package

Installez la dernière version de la bibliothèque cliente Azure Service Bus à l’aide de npm.

npm install @azure/service-bus

Environnements actuellement pris en charge

Prérequis

Configurer TypeScript

Les utilisateurs TypeScript doivent avoir installé les définitions de type Node :

npm install @types/node

Vous devez également activer compilerOptions.allowSyntheticDefaultImports dans votre tsconfig.json. Notez que si vous avez activé compilerOptions.esModuleInterop, allowSyntheticDefaultImports est activé par défaut. Pour plus d’informations, consultez manuel des options du compilateur de TypeScript.

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Outre ce qui est décrit ici, cette bibliothèque a également besoin de polyfills supplémentaires pour les modules intégrés NodeJS suivants afin de fonctionner correctement dans les navigateurs :

  • buffer
  • os
  • path
  • process

Regroupement avec Webpack

Si vous utilisez Webpack v5, vous pouvez installer les dépendances de développement suivantes

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

ajoutez ensuite ce qui suit dans votre 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"),
+    },
   },

Regroupement avec rollup

Si vous utilisez rollup bundler, installez les dépendances de développement suivantes

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

Incluez ensuite ce qui suit dans votre 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"],
+    }),
  ]
};

Pour plus d’informations sur l’utilisation de polyfills, consultez la documentation de votre bundler favori.

Prise en charge de React Native

À l’instar des navigateurs, React Native ne prend pas en charge certaines API JavaScript utilisées par cette bibliothèque SDK, vous devez donc leur fournir des polyfills. Pour plus d’informations, consultez l’exemple Messaging React Native avec Expo.

Authentifier le client

L’interaction avec Service Bus commence avec une instance de la classe ServiceBusClient . Vous pouvez vous authentifier auprès de Service Bus à l’aide d’une chaîne de connexion ou d’informations d’identification Azure Active Directory.

Utilisation d’une chaîne de connexion

Cette méthode transfère la chaîne de connexion à votre instance Service Bus. Vous pouvez obtenir la chaîne de connexion à partir du portail Azure.

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

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

Plus d’informations sur ce constructeur sont disponibles dans la documentation de l’API.

Utilisation d’informations d’identification Azure Active Directory

L’authentification avec Azure Active Directory utilise la bibliothèque Azure Identity.

L’exemple ci-dessous utilise DefaultAzureCredential, l’un des nombreux fournisseurs d’informations d’identification disponibles dans la @azure/identity bibliothèque.

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

REMARQUE : Si vous utilisez votre propre implémentation de l’interface TokenCredential contre AAD, définissez les « scopes » pour service-bus sur ce qui suit pour obtenir le jeton approprié :

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

Plus d’informations sur ce constructeur sont disponibles dans la documentation de l’API

Concepts clés

Une fois que vous avez initialisé un ServiceBusClient, vous pouvez interagir avec ces ressources dans un espace de noms Service Bus :

  • Files d’attente : permet d’envoyer et de recevoir des messages. Souvent utilisé pour la communication point à point.
  • Rubriques : contrairement aux files d’attente, les rubriques sont mieux adaptées aux scénarios de publication/abonnement. Une rubrique peut être envoyée, mais nécessite un abonnement, qui peut être plusieurs en parallèle, pour être consommé.
  • Abonnements : mécanisme de consommation à partir d’une rubrique. Chaque abonnement est indépendant et reçoit une copie de chaque message envoyé à la rubrique. Les règles et les filtres peuvent être utilisés pour personnaliser les messages reçus par un abonnement spécifique.

Pour plus d’informations sur ces ressources, consultez Qu’est-ce qu’Azure Service Bus ?.

Pour interagir avec ces ressources, il faut connaître les concepts SDK suivants :

Veuillez noter que les files d’attente, les rubriques et les abonnements doivent être créés avant d’utiliser cette bibliothèque.

Examples

Les sections suivantes fournissent des extraits de code qui couvrent certaines des tâches courantes à l’aide d’Azure Service Bus

Envoyer des messages

Une fois que vous avez créé une instance d’une ServiceBusClient classe, vous pouvez obtenir une ServiceBusSender méthode createSender que vous pouvez utiliser pour envoyer des messages.

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

Recevoir des messages

Une fois que vous avez créé une instance d’une ServiceBusClient classe, vous pouvez obtenir une à l’aide de ServiceBusReceiver la méthode 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");

Il y a deux receiveModes disponibles.

  • « peekLock » - En mode peekLock, le récepteur a un verrou sur le message pour la durée spécifiée dans la file d’attente.
  • « receiveAndDelete » : en mode receiveAndDelete, les messages sont supprimés de Service Bus au fur et à mesure de leur réception.

Si le mode receiveMode n’est pas fourni dans les options, il passe par défaut au mode « peekLock ». Vous pouvez également régler les messages reçus en mode « peekLock ».

Vous pouvez utiliser ce récepteur de l’une des 3 manières suivantes pour recevoir des messages :

Obtenir un éventail de messages

Utilisez la fonction receiveMessages qui renvoie une promesse qui se résout en un tableau de messages.

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

S’abonner à l’aide d’un gestionnaire de messages

Utilisez la méthode subscribe pour configurer des gestionnaires de messages et les faire fonctionner aussi longtemps que nécessaire.

Lorsque vous avez terminé, appelez receiver.close() pour ne plus recevoir de messages.

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

Utiliser un itérateur asynchrone

Utilisez getMessageIterator pour obtenir un itérateur asynchrone sur les messages

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
}

Régler un message

Une fois que vous avez reçu un message, vous pouvez appeler completeMessage(), abandonMessage()ou deferMessage()deadLetterMessage() sur le récepteur en fonction de la façon dont vous souhaitez régler le message.

Pour en savoir plus, veuillez lire Règlement des messages reçus

Files d’attente de lettres mortes

La file d’attente de lettres mortes est une sous-file d’attente. Chaque file d’attente ou abonnement a sa propre file d’attente de lettres mortes. Les files d’attente de lettres mortes stockent les messages qui ont été explicitement mis en lettres mortes (via receiver.deadLetterMessage()) ou les messages qui ont dépassé leur nombre maximal de remises

La création d’un récepteur pour une sous-file d’attente de lettres mortes est similaire à la création d’un récepteur pour un abonnement ou une file d’attente :

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

Des exemples complets illustrant plus en détail les files d’attente de lettres mortes :

Envoyer des messages à l’aide de Sessions

L’utilisation de sessions nécessite la création d’une file d’attente ou d’un abonnement activé pour les sessions. Vous pouvez en savoir plus sur la configuration de cette fonctionnalité dans le portail ici.

Pour envoyer des messages à une session, utilisez le ServiceBusClient pour créer un expéditeur à l’aide de createSender.

Lors de l’envoi du message, définissez la propriété dans le sessionId message pour vous assurer que votre message arrive dans la bonne session.

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

Vous pouvez en savoir plus sur le fonctionnement des sessions ici.

Recevoir des messages des sessions

L’utilisation de sessions nécessite la création d’une file d’attente ou d’un abonnement activé pour les sessions. Vous pouvez en savoir plus sur la configuration de cette fonctionnalité dans le portail ici.

Contrairement aux files d’attente ou aux abonnements non activés pour les sessions, un seul récepteur peut lire à partir d’une session à tout moment. Ceci est appliqué par le verrouillage d’une session, qui est gérée par Service Bus. D’un point de vue conceptuel, cela est similaire à la façon dont le verrouillage des messages fonctionne lors de l’utilisation peekLock du mode : lorsqu’un message (ou une session) est verrouillé, votre destinataire y a un accès exclusif.

Pour ouvrir et verrouiller une session, utilisez une instance de ServiceBusClient pour créer un SessionReceiver.

Il y a deux façons de choisir la session à ouvrir :

  1. Spécifiez un sessionId, qui verrouille une session nommée.

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

  2. Ne spécifiez pas d’ID de session. Dans ce cas, Service Bus trouvera la prochaine session disponible qui n’est pas déjà verrouillée.

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

    Vous pouvez trouver le nom de la session via la sessionId propriété sur le SessionReceiver. Si le mode receiveMode n’est pas fourni dans les options, il passe par défaut au mode « peekLock ». Vous pouvez également régler les messages reçus en mode « peekLock ».

Une fois le récepteur créé, vous pouvez choisir entre 3 façons de recevoir des messages :

Vous pouvez en savoir plus sur le fonctionnement des sessions ici.

Liste des sessions de messages

Pour découvrir quelles sessions ont des messages actifs ou un état de session dans une file d’attente ou un abonnement, utilisez 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);
}

Gérer les ressources d’un espace de noms Service Bus

ServiceBusAdministrationClient permet de gérer un espace de noms avec des opérations CRUD sur les entités (files d’attente, rubriques et abonnements) et sur les règles d’un abonnement.

  • Prend en charge l’authentification à l’aide d’une chaîne de connexion Service Bus ainsi qu’à l’aide des informations d’identification AAD d’un @azure/identity type similaire à .ServiceBusClient

Remarque : Service Bus ne prend pas encore en charge la définition de règles CORS pour les espaces de noms, et ne fonctionnera donc ServiceBusAdministrationClient pas dans le navigateur sans désactiver la sécurité web. Pour plus d’informations, cliquez ici.

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

Voici quelques étapes initiales pour commencer à diagnostiquer les problèmes. Pour plus d’informations, reportez-vous au Guide de dépannage de Service Bus.

Dépendances AMQP

La bibliothèque Service Bus dépend de la bibliothèque rhea-promise pour la gestion des connexions, l’envoi et la réception de messages via le protocole AMQP .

Logging

Vous pouvez définir la variable d’environnement suivante pour obtenir les journaux de débogage lors de l’utilisation de cette bibliothèque.

  • Obtention des journaux de débogage à partir du Kit de développement logiciel (SDK) Service Bus
export DEBUG=azure*
  • Obtention des journaux de débogage à partir du Kit de développement logiciel (SDK) Service Bus et de la bibliothèque au niveau du protocole.
export DEBUG=azure*,rhea*
  • Si vous n’êtes pas intéressé par l’affichage de la transformation du message (qui consomme beaucoup d’espace console/disque), vous pouvez définir la variable d’environnement DEBUG comme suit :
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Si vous ne vous intéressez qu’aux erreurs, vous pouvez définir la variable d’environnement DEBUG comme suit :
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Enregistrement dans un fichier

  1. Définissez la variable d’environnement DEBUG comme indiqué ci-dessus
  2. Exécutez votre script de test comme suit :
  • Les instructions de journalisation de votre script de test vont à out.log et les instructions de journalisation du kit sdk sont debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Les instructions de journalisation à partir de votre script de test et du kit sdk accédent au même fichier out.log en redirigeant stderr vers stdout (&1), puis redirigez stdout vers un fichier : 
    node your-test-script.js >out.log 2>&1
  • Journalisation des instructions à partir de votre script de test et du kit sdk accédez au même fichier out.log. 
      node your-test-script.js &> out.log

Étapes suivantes

Jetez un coup d’œil au répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque pour envoyer et recevoir des messages vers/depuis les files d’attente, les rubriques et les abonnements Service Bus.

Contributing

Si vous souhaitez contribuer à cette bibliothèque, veuillez lire le guide contribution pour en savoir plus sur la construction et le test du code.

  • Dernière mise à jour :