Partager via

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

  • Article

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, passez votre curseur sur Service Bus, puis cliquez le bouton + dans la vignette Service Bus.

    Image illustrant la sélection de Créer une ressource, puis celles de Intégration et de Service Bus, dans le 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 le Groupe de ressources, choisissez un groupe de ressources existant ou créez-en un.

    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 pas par -sb ou -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.

    6. Si vous sélectionnez le niveau Premium, indiquez si vous pouvez activer la géoréplication pour l’espace de noms. La fonctionnalité de géoréplication garantit que les métadonnées et les données d’un espace de noms sont répliquées en continu d’une région primaire vers une ou plusieurs régions secondaires.

      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.

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

      Image représentant la page Créer un espace de noms

    8. 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 représentant la page du déploiement réussi avec le lien Atteindre la ressource.

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

    Image représentant la page d’accueil de l’espace de noms Service Bus créé.

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

  1. Dans la page Espace de noms Service Bus, développez Entités dans le menu de navigation à gauche, puis 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. Sélectionnez Create (Créer).

    Image montrant la page Créer une rubrique.

Créer un abonnement à la rubrique

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

    Image montrant la sélection de la rubrique dans la liste des rubriques.

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

    Image montrant le bouton Ajouter un abonnement.

  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 montrant la page Créer un abonnement.

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.

    Capture d’écran montrant comment attribuer un rôle.

  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.

Nombre de messages entrants et sortants

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.

Messages entrants et sortants

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.

Page de rubrique mise à jour

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.

Nombre de messages actifs

Étapes suivantes

Voir la documentation et les exemples suivants :