Envoyer des messages à une rubrique Azure Service Bus et recevoir des messages à partir d’abonnements à la rubrique (JavaScript)

Dans ce tutoriel, vous allez effectuer les étapes suivantes :

  1. Créer un espace de noms Service Bus à l’aide du Portail Azure.
  2. Créer une rubrique Service Bus à l’aide du Portail Azure.
  3. Créer un abonnement Service Bus vers cette rubrique à l’aide du Portail Azure.
  4. Écrivez une application JavaScript qui utilise le package @azure/service-bus pour effectuer les actions suivantes :
    • Envoyer un ensemble de messages à la rubrique.
    • Recevoir les messages de l’abonnement.

Notes

Ce guide de démarrage rapide fournit des instructions pas à pas pour un scénario simple qui consiste à envoyer un lot de messages à une rubrique Service Bus et à recevoir ces messages à partir d’un abonnement de la rubrique. Vous trouverez des exemples JavaScript et TypeScript prédéfinis pour Azure Service Bus dans le dépôt du SDK Azure pour JavaScript sur GitHub.

Prérequis

Pour utiliser ce guide de démarrage rapide avec votre propre compte Azure, vous avez besoin des éléments suivants :

  • Installez Azure CLI, qui fournit l’authentification sans mot de passe à votre ordinateur de développement.
  • Connectez-vous avec votre compte Azure au terminal ou à l’invite de commandes avec az login.
  • Utilisez le même compte quand vous ajoutez le rôle approprié à votre ressource.
  • Exécutez le code dans le même terminal ou la même invite de commande.
  • Notez le nom de votre rubrique et abonnement pour votre espace de noms Service Bus. Vous en aurez besoin dans le code.

Notes

Créer un espace de noms dans le Portail Azure

Pour commencer à utiliser des entités de messagerie Service Bus dans Azure, vous devez d’abord créer un espace de noms avec un nom unique dans Azure. Un espace de noms fournit un conteneur d’étendue pour les ressources du Service Bus (files d’attente, thèmes, etc.) au sein de votre application.

Pour créer un espace de noms :

  1. Connectez-vous au portail Azure.

  2. Accédez à la page Tous les services.

  3. Dans la barre de navigation à gauche, sélectionnez Intégration dans la liste des catégories, passez votre curseur sur Service Bus, puis cliquez le bouton + dans la vignette Service Bus.

    Image showing selection of Create a resource, Integration, and then Service Bus in the menu.

  4. Dans l’étiquette De base de la page Créer un espace de noms, suivez ces étapes :

    1. Pour l’option Abonnement, choisissez un abonnement Azure dans lequel créer l’espace de noms.

    2. Pour l’option Groupe de ressources, choisissez un groupe de ressources existant dans lequel l’espace de noms sera utilisé, ou créez-en un nouveau.

    3. Entrez un nom pour l’espace de noms. Le nom de l’espace de noms doit respecter les conventions de nommage suivantes :

      • Le nom doit être unique dans tout Azure. Le système vérifie immédiatement si le nom est disponible.
      • Le nom doit inclure entre 6 et 50 caractères.
      • Le nom ne peut contenir que des lettres, des chiffres et des traits d’union (« - »).
      • Le nom doit commencer par une lettre, et se terminer par une lettre ou un chiffre.
      • Le nom ne se termine ni par « -sb » ni par « -mgmt ».
    4. Pour l’option Emplacement, choisissez la région dans laquelle héberger votre espace de noms.

    5. Pour le Niveau tarifaire, sélectionnez le SKU (De base, Standard ou Premium) destiné à l’espace de noms. Pour ce guide de démarrage rapide, sélectionnez Standard.

      Important

      Si vous voulez utiliser des rubriques et des abonnements, choisissez Standard ou Premium. Les rubriques/abonnements ne sont pas pris en charge dans le niveau tarifaire De base.

      Si vous avez sélectionné le SKU Premium, précisez le nombre d’unité de messagerie. Le niveau Premium isole les ressources au niveau du processeur et de la mémoire, ce qui permet d’exécuter chaque charge de travail de manière isolée. Ce conteneur de ressources est appelé unité de messagerie. Un espace de noms Premium a au moins une unité de messagerie. Vous pouvez sélectionner 1, 2, 4, 8 ou 16 unités de messagerie pour chaque espace de noms Service Bus Premium. Pour plus d’informations, consultez Messagerie Service Bus Premium.

    6. Au bas de la page, sélectionnez Examiner et créer.

      Image showing the Create a namespace page

    7. Dans la page Vérifier + créer, passez en revue les paramètres, puis sélectionnez Créer.

  5. Une fois le déploiement de la ressource réussi, sélectionnez Accéder à la ressource dans la page de déploiement.

    Image showing the deployment succeeded page with the Go to resource link.

  6. Vous voyez la page d’accueil de votre espace de noms Service Bus.

    Image showing the home page of the Service Bus namespace created.

Créer une rubrique à l’aide du Portail Azure

  1. Dans la page Espace de noms Service Bus, sélectionnez Rubriques dans le menu de gauche.

  2. Sélectionnez + Rubrique dans la barre d’outils.

  3. Entrez un nom pour la rubrique. Conservez les valeurs par défaut des autres options.

  4. Cliquez sur Créer.

    Image showing the Create topic page.

Créer un abonnement à la rubrique

  1. Sélectionnez la rubrique que vous avez créée dans la section précédente.

    Image showing the selection of topic from the list of topics.

  2. Dans la page Rubrique Service Bus, dans la barre d’outils, sélectionnez + Abonnement.

    Image showing the Add subscription button.

  3. Dans la page Créer un abonnement, procédez comme suit :

    1. Entrez S1 pour le nom de l’abonnement.

    2. Entrez 3 pour Nombre maximal de remises.

    3. Ensuite, sélectionnez Créer pour créer l’abonnement.

      Image showing the Create subscription page.

Authentifier l’application sur Azure

Ce guide de démarrage pratique vous montre deux façons de vous connecter à Azure Service Bus : sans mot de passe et avec une chaîne de connexion.

La première option vous explique comment utiliser votre principal de sécurité dans Microsoft Entra ID et le contrôle d’accès en fonction du rôle (RBAC) pour vous connecter à un espace de noms Service Bus. Vous n’avez pas à vous soucier d’avoir une chaîne de connexion codée en dur dans votre code, dans un fichier config ni dans un stockage sécurisé comme Azure Key Vault.

La deuxième option consiste à se servir d’une chaîne de connexion pour se connecter à un espace de noms Service Bus. Si vous débutez avec Azure, vous trouverez peut-être l’option chaîne de connexion plus facile à suivre. Nous vous recommandons d’utiliser l’option sans mot de passe dans les applications réelles et les environnements de production. Pour plus d’informations, consultez Authentification et autorisation. Pour en savoir plus sur l’authentification sans mot de passe, reportez-vous à la page de présentation.

Attribuer des rôles à votre utilisateur Microsoft Entra

Lors du développement localement, assurez-vous que le compte d’utilisateur qui se connecte à Azure Service Bus dispose des autorisations appropriées. Vous aurez besoin du rôle Propriétaire de données Azure Service Bus pour envoyer et recevoir des messages. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur à l’aide du Portail Azure, Azure CLI ou Azure PowerShell. Découvrez les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue.

L’exemple suivant attribue le rôle Azure Service Bus Data Owner à votre compte d’utilisateur, qui fournit un accès complet aux ressources Azure Service Bus. Dans un scénario réel, suivez le principe des privilèges minimum pour accorder aux utilisateurs uniquement les autorisations minimales nécessaires à un environnement de production plus sécurisé.

Rôles Azure intégrés pour Azure Service Bus

Pour Azure Service Bus, la gestion des espaces de noms et de toutes les ressources associées via le Portail Azure et l’API de gestion des ressources Azure est déjà protégée à l’aide du modèle Azure RBAC. Azure fournit les rôles Azure intégrés ci-dessous pour autoriser l’accès à un espace de noms Service Bus :

  • Propriétaire de données Azure Service Bus : ce rôle permet l’accès aux données de l’espace de noms Service Bus et de ses entités (files d’attente, rubriques, abonnements et filtres). Un membre de ce rôle peut envoyer et recevoir des messages à partir de files d’attente ou de rubriques et d’abonnements.
  • Expéditeur de données Azure Service Bus : utilisez ce rôle pour autoriser l’accès en envoi à l’espace de noms Service Bus et à ses entités.
  • Récepteur de données Azure Service Bus : utilisez ce rôle pour autoriser l’accès en réception à l’espace de noms Service Bus et à ses entités.

Si vous souhaitez créer un rôle personnalisé, consultez Droits requis pour les opérations Service Bus.

Ajouter un utilisateur Microsoft Entra au rôle Propriétaire Azure Service Bus

Ajoutez votre nom d’utilisateur Microsoft Entra au rôle Propriétaire de données Azure Service Bus au niveau de l’espace de noms Service Bus. Il permet à une application exécutée dans le contexte de votre compte d’utilisateur d’envoyer des messages à une file d’attente ou à une rubrique et d’en recevoir auprès d’une file d’attente ou de l’abonnement d’une rubrique.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes. Dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.

  1. Si la page Espace de noms Service Bus n’est pas ouverte sur le Portail Azure, recherchez votre espace de noms Service Bus à l’aide de la barre de recherche principale ou du volet de navigation de gauche.

  2. Dans la page vue d’ensemble, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    A screenshot showing how to assign a role.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Azure Service Bus Data Owner et sélectionnez le résultat correspondant. Ensuite, choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Utilisation de Node Package Manager (NPM) pour installer le package

  1. Pour installer le ou les packages npm requis pour Service Bus, ouvrez une invite de commandes dont le chemin contient npm, remplacez le répertoire par le dossier où vous souhaitez stocker vos exemples, puis exécutez cette commande.

  2. Installez les packages suivants :

    npm install @azure/service-bus @azure/identity
    

Envoi de messages à une rubrique

L’exemple de code suivant montre comment envoyer un lot de messages à une rubrique Service Bus. Pour plus d’informations, consultez les commentaires du code.

Vous devez avoir ouvert une session avec az login dans Azure CLI pour que votre ordinateur local fournisse l’authentification sans mot de passe requise dans ce code.

  1. Ouvrez votre éditeur favori, tel que Visual Studio Code

  2. Créez un fichier appelé sendtotopic.js et collez-y le code ci-dessous. Ce code envoie un message vers votre rubrique.

    Important

    Les informations d’identification sans mot de passe sont fournies avec DefaultAzureCredential.

    const { ServiceBusClient } = require("@azure/service-bus");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    const topicName = "<TOPIC NAME>";
    
    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" }
     ];
    
     async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createSender() can also be used to create a sender for a queue.
        const sender = sbClient.createSender(topicName);
    
        try {
            // Tries to send all messages in a single batch.
            // Will fail if the messages cannot fit in a batch.
            // await sender.sendMessages(messages);
    
            // create a batch object
            let batch = await sender.createMessageBatch();
            for (let i = 0; i < messages.length; i++) {
                // for each message in the array
    
                // try to add the message to the batch
                if (!batch.tryAddMessage(messages[i])) {
                    // if it fails to add the message to the current batch
                    // send the current batch as it is full
                    await sender.sendMessages(batch);
    
                    // then, create a new batch
                    batch = await sender.createMessageBatch();
    
                    // now, add the message failed to be added to the previous batch to this batch
                    if (!batch.tryAddMessage(messages[i])) {
                        // if it still can't be added to the batch, the message is probably too big to fit in a batch
                        throw new Error("Message too big to fit in a batch");
                    }
                }
            }
    
            // Send the last created batch of messages to the topic
            await sender.sendMessages(batch);
    
            console.log(`Sent a batch of messages to the topic: ${topicName}`);
    
            // Close the sender
            await sender.close();
        } finally {
            await sbClient.close();
        }
    }
    
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
     });
    
  3. Remplacez <SERVICE BUS NAMESPACE CONNECTION STRING> par la chaîne de connexion de votre espace de noms Service Bus,

  4. et remplacez <TOPIC NAME> par le nom de la rubrique.

  5. Ensuite, exécutez la commande à partir d’une invite de commandes pour exécuter ce fichier.

    node sendtotopic.js
    
  6. Vous devez voir la sortie suivante.

    Sent a batch of messages to the topic: mytopic
    

Réception des messages d’un abonnement

Vous devez avoir ouvert une session avec az login dans Azure CLI pour que votre ordinateur local fournisse l’authentification sans mot de passe requise dans ce code.

  1. Ouvrez votre éditeur favori, tel que Visual Studio Code

  2. Créez un fichier nommé receivefromsubscription.js et collez-y le code suivant. Pour plus d’informations, consultez les commentaires du code.

    const { delay, ServiceBusClient, ServiceBusMessage } = require("@azure/service-bus");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    const topicName = "<TOPIC NAME>";
    const subscriptionName = "<SUBSCRIPTION NAME>";
    
     async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createReceiver() can also be used to create a receiver for a queue.
        const receiver = sbClient.createReceiver(topicName, subscriptionName);
    
        // function to handle messages
        const myMessageHandler = async (messageReceived) => {
            console.log(`Received message: ${messageReceived.body}`);
        };
    
        // function to handle any errors
        const myErrorHandler = async (error) => {
            console.log(error);
        };
    
        // subscribe and specify the message and error handlers
        receiver.subscribe({
            processMessage: myMessageHandler,
            processError: myErrorHandler
        });
    
        // Waiting long enough before closing the sender to send messages
        await delay(5000);
    
        await receiver.close();
        await sbClient.close();
    }
    
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
     });
    
  3. Remplacez <SERVICE BUS NAMESPACE CONNECTION STRING> par la chaîne de connexion à l’espace de noms,

  4. et remplacez <TOPIC NAME> par le nom de la rubrique.

  5. Remplacez <SUBSCRIPTION NAME> par le nom de l’abonnement à la rubrique.

  6. Ensuite, exécutez la commande à partir d’une invite de commandes pour exécuter ce fichier.

    node receivefromsubscription.js
    

Vous devez voir la sortie suivante.

Received message: Albert Einstein
Received message: Werner Heisenberg
Received message: Marie Curie
Received message: Steven Hawking
Received message: Isaac Newton
Received message: Niels Bohr
Received message: Michael Faraday
Received message: Galileo Galilei
Received message: Johannes Kepler
Received message: Nikolaus Kopernikus

Dans le portail Azure, accédez à votre espace de noms Service Bus, basculez vers Rubriques dans le volet du bas et sélectionnez votre rubrique pour voir la page Rubrique Service Bus correspondant à votre rubrique. Dans cette page, vous devez voir 10 messages entrants et 10 messages sortants dans le graphique Messages.

Incoming and outgoing messages

Si la fois suivante vous exécutez uniquement l’application d’envoi, dans la page Rubrique Service Bus, vous voyez 20 messages entrants (10 nouveaux), mais 10 messages sortants.

Updated topic page

Dans cette page, si vous sélectionnez un abonnement dans le volet du bas, vous accédez à la page Abonnement Service Bus. Elle indique entre autres le nombre de messages actifs et le nombre de messages de lettres mortes. Dans cet exemple, il y a 10 messages actifs qui n’ont pas encore été reçus par un récepteur.

Active message count

Résolution des problèmes

Si une erreur survient quand vous exécutez la version sans mot de passe du code JavaScript concernant les revendications requises, vérifiez que vous vous êtes connecté avec la commande az login d’Azure CLI et que le rôle approprié est appliqué à votre compte d’utilisateur Azure.

Nettoyer les ressources

Accédez à votre espace de noms Service Bus dans le Portail Azure, puis sélectionnez Supprimer sur le Portail Azure pour supprimer l’espace de noms et la file d’attente qu’il contient.

Étapes suivantes

Voir la documentation et les exemples suivants :