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

Dans ce guide de démarrage rapide, vous allez écrire du code Java à l’aide du package azure-messaging-servicebus pour envoyer des messages à une rubrique Azure Service Bus, puis vous recevrez les messages des abonnements à cette rubrique.

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 Java prédéfinis pour Azure Service Bus dans le dépôt du kit SDK Azure pour Java sur GitHub.

Conseil

Si vous utilisez des ressources Azure Service Bus dans une application Spring, nous vous recommandons de considérer Spring Cloud Azure comme alternative. Azure Spring Cloud est un projet open source qui fournit une intégration de Spring fluide aux services Azure. Pour en savoir plus sur Spring Cloud Azure et pour voir un exemple d’utilisation de Service Bus, consultez Spring Cloud Stream avec Azure Service Bus.

Prérequis

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, pointez avec la souris sur Service Bus, puis sélectionnez 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.

Envoi de messages à une rubrique

Dans cette section, vous allez créer un projet de console Java et ajouter du code pour envoyer des messages à la rubrique que vous avez créée.

Créer un projet de console Java

Créez un projet Java avec Eclipse ou un outil de votre choix.

Configuration de votre application pour l’utilisation de Service Bus

Ajoutez des références aux bibliothèques Azure Core et Azure Service Bus.

Si vous utilisez Eclipse et avez créé une application de console Java, convertissez votre projet Java en Maven : faites un clic droit sur le projet dans la fenêtre Explorateur de package, puis sélectionnez Configurer – >Convertir en projet Maven. Ajoutez ensuite des dépendances à ces deux bibliothèques, comme indiqué dans l’exemple suivant.

Mettez à jour le fichier pom.xml pour ajouter des dépendances aux packages Azure Service Bus et Azure Identity.

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-messaging-servicebus</artifactId>
            <version>7.13.3</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.8.0</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

Ajouter du code pour envoyer des messages à la rubrique

  1. Ajoutez les instructions import suivantes au début du fichier Java.

    import com.azure.messaging.servicebus.*;
    import com.azure.identity.*;
    
    import java.util.concurrent.TimeUnit;
    import java.util.Arrays;
    import java.util.List;
    
  2. Dans la classe , définissez des variables pour contenir la chaîne de connexion (non nécessaire pour le scénario sans mot de passe), le nom de la rubrique et le nom de l’abonnement.

    static String topicName = "<TOPIC NAME>";
    static String subName = "<SUBSCRIPTION NAME>";
    

    Important

    Remplacez <TOPIC NAME> par le nom de la rubrique et <SUBSCRIPTION NAME> par le nom de l’abonnement de la rubrique.

  3. Ajoutez une méthode nommée sendMessage dans la classe pour envoyer un message à la rubrique.

    Important

    Remplacez NAMESPACENAME par le nom de votre espace de noms Service Bus.

    static void sendMessage()
    {
        // create a token using the default Azure credential
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        ServiceBusSenderClient senderClient = new ServiceBusClientBuilder()
                .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
                .credential(credential)
                .sender()
                .topicName(topicName)
                .buildClient();
    
        // send one message to the topic
        senderClient.sendMessage(new ServiceBusMessage("Hello, World!"));
        System.out.println("Sent a single message to the topic: " + topicName);
    }
    
    
  4. Ajoutez une méthode nommée createMessages dans la classe pour créer une liste de messages. En général, vous recevez ces messages à partir de différentes parties de votre application. Ici, nous créons une liste d’exemples de messages.

    static List<ServiceBusMessage> createMessages()
    {
        // create a list of messages and return it to the caller
        ServiceBusMessage[] messages = {
                new ServiceBusMessage("First message"),
                new ServiceBusMessage("Second message"),
                new ServiceBusMessage("Third message")
        };
        return Arrays.asList(messages);
    }
    
  5. Ajoutez une méthode nommée sendMessageBatch pour envoyer des messages à la rubrique que vous avez créée. Cette méthode crée un ServiceBusSenderClient pour la rubrique, appelle la méthode createMessages pour obtenir la liste des messages, prépare un ou plusieurs lots, et envoie les lots à la rubrique.

    Important

    Remplacez NAMESPACENAME par le nom de votre espace de noms Service Bus.

    static void sendMessageBatch()
    {
        // create a token using the default Azure credential
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        ServiceBusSenderClient senderClient = new ServiceBusClientBuilder()
                .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
                .credential(credential)
                .sender()
                .topicName(topicName)
                .buildClient();
    
        // Creates an ServiceBusMessageBatch where the ServiceBus.
        ServiceBusMessageBatch messageBatch = senderClient.createMessageBatch();
    
        // create a list of messages
        List<ServiceBusMessage> listOfMessages = createMessages();
    
        // We try to add as many messages as a batch can fit based on the maximum size and send to Service Bus when
        // the batch can hold no more messages. Create a new batch for next set of messages and repeat until all
        // messages are sent.
        for (ServiceBusMessage message : listOfMessages) {
            if (messageBatch.tryAddMessage(message)) {
                continue;
            }
    
            // The batch is full, so we create a new batch and send the batch.
            senderClient.sendMessages(messageBatch);
            System.out.println("Sent a batch of messages to the topic: " + topicName);
    
            // create a new batch
            messageBatch = senderClient.createMessageBatch();
    
            // Add that message that we couldn't before.
            if (!messageBatch.tryAddMessage(message)) {
                System.err.printf("Message is too large for an empty batch. Skipping. Max size: %s.", messageBatch.getMaxSizeInBytes());
            }
        }
    
        if (messageBatch.getCount() > 0) {
            senderClient.sendMessages(messageBatch);
            System.out.println("Sent a batch of messages to the topic: " + topicName);
        }
    
        //close the client
        senderClient.close();
    }
    

Réception des messages d’un abonnement

Dans cette section, vous allez ajouter du code pour récupérer les messages à partir d’un abonnement à la rubrique.

  1. Ajoutez une méthode nommée receiveMessages pour recevoir des messages à partir de l’abonnement. Cette méthode crée un ServiceBusProcessorClient pour l’abonnement en spécifiant un gestionnaire pour le traitement des messages et un autre pour la gestion des erreurs. Ensuite, elle démarre le processeur, attend quelques secondes, imprime les messages reçus, puis arrête et ferme le processeur.

    Important

    • Remplacez NAMESPACENAME par le nom de votre espace de noms Service Bus.
    • Dans le code, remplacez ServiceBusTopicTest dans ServiceBusTopicTest::processMessage par le nom de votre classe.
    // handles received messages
    static void receiveMessages() throws InterruptedException
    {
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        // Create an instance of the processor through the ServiceBusClientBuilder
        ServiceBusProcessorClient processorClient = new ServiceBusClientBuilder()
            .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
            .credential(credential)
            .processor()
            .topicName(topicName)
            .subscriptionName(subName)
            .processMessage(context -> processMessage(context))
            .processError(context -> processError(context))
            .buildProcessorClient();
    
        System.out.println("Starting the processor");
        processorClient.start();
    
        TimeUnit.SECONDS.sleep(10);
        System.out.println("Stopping and closing the processor");
        processorClient.close();
    }
    
  2. Ajoutez la méthode processMessage pour traiter un message reçu de l’abonnement Service Bus.

    private static void processMessage(ServiceBusReceivedMessageContext context) {
        ServiceBusReceivedMessage message = context.getMessage();
        System.out.printf("Processing message. Session: %s, Sequence #: %s. Contents: %s%n", message.getMessageId(),
            message.getSequenceNumber(), message.getBody());
    }
    
  3. Ajoutez la méthode processError pour gérer les messages d’erreur.

    private static void processError(ServiceBusErrorContext context) {
        System.out.printf("Error when receiving messages from namespace: '%s'. Entity: '%s'%n",
            context.getFullyQualifiedNamespace(), context.getEntityPath());
    
        if (!(context.getException() instanceof ServiceBusException)) {
            System.out.printf("Non-ServiceBusException occurred: %s%n", context.getException());
            return;
        }
    
        ServiceBusException exception = (ServiceBusException) context.getException();
        ServiceBusFailureReason reason = exception.getReason();
    
        if (reason == ServiceBusFailureReason.MESSAGING_ENTITY_DISABLED
            || reason == ServiceBusFailureReason.MESSAGING_ENTITY_NOT_FOUND
            || reason == ServiceBusFailureReason.UNAUTHORIZED) {
            System.out.printf("An unrecoverable error occurred. Stopping processing with reason %s: %s%n",
                reason, exception.getMessage());
        } else if (reason == ServiceBusFailureReason.MESSAGE_LOCK_LOST) {
            System.out.printf("Message lock lost for message: %s%n", context.getException());
        } else if (reason == ServiceBusFailureReason.SERVICE_BUSY) {
            try {
                // Choosing an arbitrary amount of time to wait until trying again.
                TimeUnit.SECONDS.sleep(1);
            } catch (InterruptedException e) {
                System.err.println("Unable to sleep for period of time");
            }
        } else {
            System.out.printf("Error source %s, reason %s, message: %s%n", context.getErrorSource(),
                reason, context.getException());
        }
    }
    
  4. Mettez à jour la méthode main pour appeler les méthodes sendMessage, sendMessageBatchet receiveMessages, et pour lever InterruptedException.

    public static void main(String[] args) throws InterruptedException {
        sendMessage();
        sendMessageBatch();
        receiveMessages();
    }
    

Exécuter l’application

Exécutez le programme pour obtenir une sortie de ce type :

  1. Si vous utilisez Eclipse, faites un clic droit sur le projet, sélectionnez Exporter, développez Java, sélectionnez Fichier JAR exécutable, puis suivez les étapes pour créer un fichier JAR exécutable.

  2. Si vous êtes connecté à l’ordinateur à l’aide d’un compte d’utilisateur différent du compte d’utilisateur ajouté au rôle propriétaire des données Azure Service Bus, suivez les étapes suivantes. Sinon, ignorez cette étape et passez à l’exécution du fichier JAR à l’étape suivante.

    1. Installez Azure CLI sur votre machine.

    2. Exécutez la commande CLI suivante pour vous connecter à Azure. Utilisez le même compte d’utilisateur que celui que vous avez ajouté au rôle propriétaire des données Azure Service Bus.

      az login
      
  3. Exécutez le fichier JAR à l’aide de la commande suivante.

    java -jar <JAR FILE NAME>
    
  4. Vous voyez la sortie suivante dans la fenêtre de console.

    Sent a single message to the topic: mytopic
    Sent a batch of messages to the topic: mytopic
    Starting the processor
    Processing message. Session: e0102f5fbaf646988a2f4b65f7d32385, Sequence #: 1. Contents: Hello, World!
    Processing message. Session: 3e991e232ca248f2bc332caa8034bed9, Sequence #: 2. Contents: First message
    Processing message. Session: 56d3a9ea7df446f8a2944ee72cca4ea0, Sequence #: 3. Contents: Second message
    Processing message. Session: 7bd3bd3e966a40ebbc9b29b082da14bb, Sequence #: 4. Contents: Third message
    

Dans la page Vue d’ensemble de l’espace de noms Service Bus dans le portail Azure, vous pouvez voir le nombre de messages entrants et sortants. Attendez environ une minute puis actualisez la page pour voir les valeurs les plus récentes.

Incoming and outgoing message count

Basculez vers l’onglet Rubriques dans le volet du milieu inférieur, puis sélectionnez la rubrique pour afficher la page Rubrique Service Bus correspondant à votre rubrique. Dans cette page, vous devez voir quatre messages entrants et quatre messages sortants dans le graphique Messages.

Incoming and outgoing messages

Si vous commentez l’appel receiveMessages dans la méthode main et que vous réexécutez l’application, dans la page Rubrique Service Bus vous verrez huit messages entrants (quatre nouveaux) mais quatre messages sortants.

Updated topic page

Dans cette page, si vous sélectionnez un abonnement, 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, quatre messages actifs n’ont pas encore été reçus par un récepteur.

Active message count

Étapes suivantes

Voir la documentation et les exemples suivants :