Démarrage rapide : bibliothèque cliente Stockage File d’attente Azure pour Java

  • Article

Familiarisez-vous avec la bibliothèque de client Storage File d’attente Azure pour Java. Le Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages dans le but de les récupérer et de les traiter plus tard. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (Maven) | Exemples

Utilisez la bibliothèque de client Stockage File d’attente Azure pour Java afin d’effectuer les opérations suivantes :

  • Créer une file d’attente
  • Ajouter des messages à une file d’attente
  • Afficher un aperçu des messages d’une file d’attente
  • Mettre à jour un message dans une file d’attente
  • Obtention de la longueur de la file d'attente
  • Recevoir les messages d’une file d’attente
  • Supprimer des messages d’une file d’attente
  • Suppression d'une file d'attente

Prérequis

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque de client Stockage File d’attente Azure pour Java.

Créer le projet

Créez une application Java nommée queues-quickstart.

  1. Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez Maven pour créer une application de console nommée queues-quickstart. Tapez la commande mvn suivante pour créer un projet Java « hello world ! ».

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.queues.quickstart `
    --define artifactId=queues-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Le résultat de la génération du projet doit ressembler à ceci :

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.394 s
[INFO] Finished at: 2019-12-03T09:58:35-08:00
[INFO] ------------------------------------------------------------------------

  3. Basculez dans le répertoire queues-quickstart créé.

    cd queues-quickstart

Installer les packages

Ouvrez le fichier pom.xml dans votre éditeur de texte.

Ajoutez azure-sdk-bom pour établir une dépendance sur la dernière version de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. L’utilisation d’azure-sdk-bom vous empêche de devoir spécifier la version de chaque dépendance individuelle. Pour en savoir plus sur la nomenclature, consultez le fichier Lisez-moi de la nomenclature du SDK Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Ajoutez ensuite les éléments dependency suivants au groupe de dépendances. La dépendance azure-identity est nécessaire pour les connexions sans mot de passe aux services Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Configurer le framework d’application

À partir du répertoire de projet :

  1. Accédez au répertoire /src/main/java/com/queues/quickstart
  2. Ouvrez le fichier App.java dans votre éditeur
  3. Supprimez l’instruction System.out.println("Hello, world");
  4. Ajoutez des directives import.

Voici le code :

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Authentification auprès d’Azure

Les requêtes d’application vers les Services Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code.

Vous pouvez également autoriser directement les requêtes adressées aux services Azure à l’aide de mots de passe, de chaînes de connexion ou d’autres informations d’identification. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer les secrets dans un emplacement non sécurisé. Toute personne ayant accès au mot de passe ou à la clé secrète est en mesure de s’authentifier. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

DefaultAzureCredential est une classe fournie par la bibliothèque de client Azure Identity pour Java. Pour en savoir plus sur DefaultAzureCredential, consultez la vue d’ensemble de DefaultAzureCredential. DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution. Cette approche permet à votre application d’utiliser différentes méthodes d’authentification dans différents environnements (local ou production) sans implémenter de code spécifique à l’environnement.

Par exemple, votre application peut s’authentifier à l’aide de vos informations d’identification de connexion Azure CLI lors du développement local, puis utiliser une identité managée une fois qu’elle a été déployée sur Azure. Aucune modification du code n’est requise pour cette transition.

Lors du développement localement, assurez-vous que le compte d’utilisateur qui accède aux données de file d'attente dispose des autorisations appropriées. Vous aurez besoin du Contributeur aux données de file d'attente de stockage pour lire et écrire des données blob. 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. Vous pouvez en savoir plus sur les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue .

Dans ce scénario, vous allez attribuer des autorisations à votre compte d’utilisateur, étendues au compte de stockage, pour suivre le Principe des privilèges minimum. Cette pratique offre aux utilisateurs uniquement les autorisations minimales nécessaires et crée des environnements de production plus sécurisés.

L’exemple suivant attribue le rôle Contributeur aux données file d'attente du stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données file d'attente dans votre compte de stockage.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes, mais 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. Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble du compte de stockage, 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.

  1. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données file d'attente du stockage, sélectionnez le résultat correspondant, puis choisissez Suivant.

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

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

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

Modèle objet

Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages. La taille maximale d’un message de file d’attente est de 64 Ko. Une file d’attente peut contenir des millions de messages, dans la limite de la capacité totale d’un compte de stockage. Les files d’attente sont couramment utilisées pour créer un backlog de travail à traiter de façon asynchrone. Le Stockage File d’attente offre trois types de ressources :

  • Compte de stockage : Tous les accès à Azure Storage passent par un compte de stockage. Pour plus d’informations sur les comptes de stockage, consultez Vue d’ensemble des comptes de stockage.
  • File d’attente : une file d’attente contient un ensemble de messages. Tous les messages doivent être dans une file d’attente. Notez que le nom de la file d’attente doit être en minuscules. Pour plus d'informations sur l’affectation de noms à des files d’attente, consultez Affectation de noms pour les files d'attente et les métadonnées.
  • Message : message dans n’importe quel format d’une taille maximale de 64 Ko. Un message peut rester dans la file d’attente pendant un maximum de 7 jours. Pour les versions du 29 juillet 2017 ou ultérieures, la durée de vie maximale peut être n’importe quel nombre positif, ou -1 indiquant que le message n’expire pas. Si ce paramètre est omis, la valeur par défaut de la durée de vie est de sept jours.

Le diagramme suivant montre la relation entre ces ressources.

Diagram of Queue storage architecture

Utilisez les classes Java suivantes pour interagir avec ces ressources :

  • QueueClientBuilder : la classe QueueClientBuilder configure et instancie un objet QueueClient.
  • QueueServiceClient : QueueServiceClient vous permet de gérer toutes les files d’attente de votre compte de stockage.
  • QueueClient : la classe QueueClient vous permet de gérer et de manipuler une file d’attente individuelle et ses messages.
  • QueueMessageItem : la classe QueueMessageItem représente les objets individuels retournés lors de l’appel de ReceiveMessages dans une file d’attente.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les actions suivantes avec la bibliothèque de client Stockage File d’attente Azure pour Java :

Autoriser l’accès et créer un objet client

Vérifiez que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez attribué le rôle. Vous pouvez vous authentifier via Azure CLI, Visual Studio Code ou Azure PowerShell.

Connectez-vous à Azure via Azure CLI à l’aide de la commande suivante :

az login

Une fois authentifié, vous pouvez créer et autoriser un objet QueueClientà l’aide deDefaultAzureCredential pour accéder aux données de file d’attente dans le compte de stockage. DefaultAzureCredential découvre et utilise automatiquement le compte avec lequel vous vous êtes connecté à l’étape précédente.

Pour autoriser l’utilisation DefaultAzureCredentialde , vérifiez que vous avez ajouté la dépendance azure-identity dans pom.xml, comme décrit dans Installer les packages. Veillez également à ajouter une directive d’importation pour com.azure.identity dans le fichier App.java :

import com.azure.identity.*;

Choisissez un nom pour la file d’attente et créez une instance de la classeQueueClient, en utilisant DefaultAzureCredential pour l’autorisation. Nous utilisons cet objet client pour créer et interagir avec la ressource de file d’attente dans le compte de stockage.

Important

Les noms de file d’attente peuvent contenir uniquement des lettres minuscules, des chiffres et des traits d’union, et doivent commencer par une lettre ou un nombre. Chaque trait d’union doit être précédé et suivi d’un caractère autre qu’un tiret. Le nom doit avoir entre 3 et 63 caractères. Pour plus d’informations sur le nommage des files d’attente, consultez Nommage des files d’attente et des métadonnées.

Ajoutez ce code à l’intérieur de la main méthode et veillez à remplacer la valeur de l’espace <storage-account-name> réservé :

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Notes

Les messages que vous envoyez à l’aide de la classe QueueClient doivent être dans un format pouvant être inclus dans une requête XML avec encodage UTF-8. Si vous le souhaitez, vous pouvez définir l’option QueueMessageEncoding sur BASE64 pour gérer les messages non conformes.

Créer une file d’attente

Avec l’objet QueueClient, appelez la méthode create pour créer la file d’attente dans votre compte de stockage.

Ajoutez ce code à la fin de la méthode main :

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

Ajouter des messages à une file d’attente

L’extrait de code suivant ajoute des messages à la file d’attente en appelant la méthode sendMessage. Il enregistre également un SendMessageResult retourné à partir d’un appel de sendMessage. Le résultat est utilisé pour mettre à jour le message ultérieurement dans le programme.

Ajoutez ce code à la fin de la méthode main :

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Afficher un aperçu des messages d’une file d’attente

Affichez un aperçu des messages de la file d’attente en appelant la méthode peekMessages. Cette méthode récupère un ou plusieurs messages du début de la file d’attente, mais ne modifie pas la visibilité du message.

Ajoutez ce code à la fin de la méthode main :

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Mettre à jour un message dans une file d’attente

Mettez à jour le contenu d’un message en appelant la méthode updateMessage. Cette méthode peut changer le contenu et le délai d’expiration de la visibilité d’un message. Le contenu du message doit être une chaîne encodée en UTF-8 d’une taille maximale de 64 Ko. Avec le nouveau contenu du message, transmettez l’ID du message et la réception POP en utilisant le SendMessageResult qui a été enregistré dans le code. L’ID du message et la réception POP identifient le message à mettre à jour.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Obtention de la longueur de la file d'attente

Vous pouvez obtenir une estimation du nombre de messages dans une file d'attente.

La méthode getProperties retourne plusieurs valeurs, y compris le nombre de messages qui se trouvent dans une file d’attente. Ce nombre est approximatif étant donné que des messages peuvent être ajoutés ou supprimés après votre demande. La méthode getApproximateMessageCount retourne la dernière valeur récupérée par l’appel à getProperties, sans appeler le Stockage File d’attente.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

Recevoir et supprimer des messages d’une file d’attente

Téléchargez les messages ajoutés en appelant la méthode receiveMessages. L’exemple de code supprime également les messages de la file d’attente une fois qu’ils sont reçus et traités. Dans ce cas, le traitement affiche simplement le message sur la console.

Avant de recevoir et de supprimer les messages, l’application s’interrompt dans l’attente d’une entrée de l’utilisateur en appelant System.console().readLine();. Vérifiez dans votre portail Azure que les ressources ont été créées correctement avant d’être supprimées. Les messages qui ne sont pas supprimés explicitement redeviennent visibles dans la file d’attente et peuvent éventuellement être de nouveau traités.

Ajoutez ce code à la fin de la méthode main :

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Lorsque vous appelez la méthode receiveMessages, vous pouvez éventuellement spécifier une valeur pour maxMessages, qui correspond au nombre de messages à récupérer dans la file d’attente. La valeur par défaut est de 1 message et la valeur maximale est de 32 messages. Vous pouvez également spécifier une valeur pour visibilityTimeout, qui masque les messages aux autres opérations pendant la période d’expiration. La valeur par défaut est 30 secondes.

Suppression d'une file d'attente

Le code suivant nettoie les ressources créées par l’application en supprimant la file d’attente avec la méthode Delete.

Ajoutez ce code à la fin de la méthode main :

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

Exécuter le code

Cette application crée trois messages et les ajoute à une file d’attente Azure. Le code liste les messages dans la file d’attente, puis les récupère et les supprime avant de supprimer la file d’attente.

Dans la fenêtre de votre console, accédez au répertoire de l’application, puis générez et exécutez l’application.

mvn compile

Ensuite, générez le package.

mvn package

Utilisez la commande mvn suivante pour exécuter l’application.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

La sortie de l’application ressemble à l’exemple suivant :

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Quand l’application s’interrompt avant de recevoir des messages, vérifiez votre compte de stockage dans le portail Azure. Vérifiez que les messages se trouvent dans la file d’attente.

Appuyez sur la touche Enter pour recevoir et supprimer les messages. Quand vous y êtes invité, réappuyez sur la touche Enter pour supprimer la file d’attente et terminer la démonstration.

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer une file d’attente et à y ajouter des messages à l’aide de code Java. Ensuite, vous avez appris à afficher un aperçu des messages, à les récupérer et à les supprimer. Enfin, vous avez appris à supprimer une file d’attente de messages.

Pour obtenir des tutoriels, des exemples, des guides de démarrage rapide et d’autres documents, visitez :

Azure pour les développeurs cloud Java