Bibliothèque cliente Azure Service Bus pour JavaScript - version 7.9.5

Azure Service Bus est un service de messagerie cloud très 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éer/Obtenir/Supprimer/Mettre à jour/Lister des files d’attente/Rubriques/Abonnements/Règles dans un espace de noms Azure Service Bus.

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

Liens clés :

• Code source
• Package (npm)
• Documentation de référence de l’API
• Documentation du produit
• Exemples
• Guide de résolution des problèmes

REMARQUE : si vous utilisez la version 1.1.10 ou une version ulté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

Prise en main

Installer le package

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

npm install @azure/service-bus

Environnements actuellement pris en charge

• Versions LTS de Node.js

Prérequis

• Un abonnement Azure
• Espace de noms Service Bus

Configurer TypeScript

Les utilisateurs TypeScript doivent avoir installé des définitions de type de nœud :

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 le manuel des options du compilateur de TypeScript .

Ensemble JavaScript

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

En plus de ce qui est décrit ici, cette bibliothèque a également besoin de polyfills supplémentaires pour les modules intégrés principaux 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 les éléments suivants à 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 un cumul cumulatif

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 les éléments suivants 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"],
+    }),
  ]
};

Consultez la documentation de votre bundler favori pour plus d’informations sur l’utilisation de polyfills.

Prise en charge native de React

Comme pour les 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 par 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.

A l'aide d'une chaîne de connexion

Cette méthode prend la chaîne de connexion à votre instance Service Bus. Vous pouvez obtenir cette chaîne de connexion sur le portail Azure.

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

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

Pour plus d’informations sur ce constructeur, consultez 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 à partir de la @azure/identity bibliothèque.

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

REMARQUE : si vous utilisez votre propre implémentation de l’interface TokenCredential sur AAD, définissez les « étendues » pour service-bus sur les valeurs suivantes 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 plus adaptées aux scénarios de publication/abonnement. Une rubrique peut être envoyée à, mais nécessite un abonnement, dont il peut y avoir plusieurs en parallèle, à partir duquel consommer.
• Abonnements : mécanisme à utiliser à 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, vous devez être familiarisé avec les concepts suivants du Kit de développement logiciel (SDK) :

• Envoyez des messages à une file d’attente ou à une rubrique, à l’aide d’un ServiceBusSender créé à l’aide de ServiceBusClient.createSender().
• Recevez des messages, à partir d’une file d’attente ou d’un abonnement, à l’aide d’un ServiceBusReceiver créé à l’aide de ServiceBusClient.createReceiver().
• Recevez des messages, à partir de files d’attente ou d’abonnements activés pour la session, à l’aide d’un ServiceBusSessionReceiver créé à l’aide ServiceBusClient.acceptSession() de ou ServiceBusClient.acceptNextSession().

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

Exemples

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

• Envoyer des messages
• Recevoir des messages
• Régler un message
• Files d’attente de lettres mortes
• Envoyer des messages à l’aide de sessions
• Recevoir des messages à partir de sessions
• Gérer les ressources d’un espace de noms Service Bus
• Exemples supplémentaires

Envoyer des messages

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

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 un ServiceBusReceiver à l’aide de la méthode createReceiver .

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

Il y a deux receiveModes disponibles.

• « peekLock » : en mode peekLock, le récepteur dispose d’un verrou sur le message pendant la durée spécifiée dans la file d’attente.
• « receiveAndDelete » : en mode receiveAndDelete, les messages sont supprimés de Service Bus à mesure qu’ils sont reçus.

Si le mode receiveMode n’est pas fourni dans les options, il utilise par défaut le 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 façons suivantes pour recevoir des messages :

Obtenir un tableau de messages

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

const myMessages = await receiver.receiveMessages(10);

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

Utilisez la méthode d’abonnement pour configurer des gestionnaires de messages et l’exécuter aussi longtemps que vous en avez besoin.

Lorsque vous avez terminé, appelez receiver.close() pour arrêter de recevoir d’autres messages.

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

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

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

Régler un message

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

Pour en savoir plus, consultez Settling Received Messages

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 lettre morte (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 :

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

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

• Utilisation de receiver.deadLetterMessage() pour envoyer explicitement des messages à la sous-file d’attente de lettres mortes
• Réception de messages de la sous-file d’attente de lettres mortes

Envoyer des messages à l’aide de sessions

L’utilisation de sessions vous oblige à créer une file d’attente ou un abonnement activé pour la session. Vous pouvez en savoir plus sur la configuration de cette fonctionnalité dans le portail ici.

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

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

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 de sessions

L’utilisation de sessions vous oblige à créer une file d’attente ou un abonnement activé pour la session. 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 la session, un seul récepteur peut lire à tout moment à partir d’une session. Cela est appliqué en verrouillant une session, qui est gérée par Service Bus. D’un point de vue conceptuel, cela est similaire au fonctionnement du verrouillage des messages lors de l’utilisation peekLock du mode : quand un message (ou une session) est verrouillé, votre récepteur a un accès exclusif à celui-ci.

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

Il existe 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 utilise par défaut le 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 :

• Obtenir un tableau de messages
• S’abonner à l’aide d’un gestionnaire de messages
• Utiliser un itérateur asynchrone

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

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

ServiceBusAdministrationClient vous 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 avec une chaîne de connexion Service Bus ainsi qu’avec les informations d’identification AAD de @azure/identity similaires à ServiceBusClient.

Remarque : Service Bus ne prend pas encore en charge la définition de règles CORS pour les espaces de noms. Par conséquent ServiceBusAdministrationClient , il ne fonctionne pas dans le navigateur sans désactiver la sécurité web. Pour plus d’informations, reportez-vous ici.

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

• Exemple de référence - administrationClient.ts

Dépannage

Voici quelques étapes initiales pour commencer à diagnostiquer les problèmes. Pour plus d’informations, consultez le Guide de résolution des problèmes 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 .

Journalisation

Vous pouvez définir la variable d’environnement suivante pour afficher les journaux de débogage quand vous utilisez 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 de niveau protocole.

export DEBUG=azure*,rhea*

• Si vous n’êtes pas intéressé par l’affichage de la transformation de message (qui consomme beaucoup d’espace sur la 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 vous intéressez uniquement 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

Journalisation dans un fichier

1. Définir 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 de développement logiciel (SDK) vont à debug.log.

  node your-test-script.js > out.log 2>debug.log
  

• Les instructions de journalisation de votre script de test et du sdk vont au même fichier out.log en redirigeant stderr vers stdout (&1), puis en redirigeant stdout vers un fichier :

  node your-test-script.js >out.log 2>&1
  

• Les instructions de journalisation de votre script de test et du Kit de développement logiciel (SDK) vont dans le même fichier out.log.

    node your-test-script.js &> out.log
  

Étapes suivantes

Consultez le 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 des files d’attente, des rubriques et des abonnements Service Bus.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.