Partager via

Démarrage rapide : Bibliothèque cliente de stockage de files d'attente Azure pour Java

Familiarisez-vous avec la bibliothèque de client Storage File d’attente Azure pour Java. Le service de File d’attente Azure permet de stocker un grand nombre de messages pour leur récupération et traitement ultérieurs. Suivez ces étapes pour installer le package et essayer un exemple de code pour les tâches de base.

Documentation de référence APICode source de la bibliothèquePackage (Maven)Exemples

Utilisez la bibliothèque cliente Azure Queue Storage pour Java pour :

  • Créer une file d’attente
  • Ajouter des messages à une file d’attente
  • Aperçu des messages dans une file d’attente
  • Mettre à jour un message dans une file d’attente
  • Obtenir la longueur de la file d’attente
  • Réception des messages d'une file d'attente
  • Supprimer des messages d’une file d’attente
  • Suppression d'une file d'attente

Prerequisites

Configuration

Cette section vous guide tout au long de la préparation d’un projet pour travailler avec la bibliothèque client Azure Queue Storage 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 console avec le nom files d’attente-démarrage rapide. Tapez la commande suivante mvn pour créer un « Hello, world ! » Projet Java.

    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 génération du projet devrait 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 vers le répertoire nouvellement créé queues-quickstart.

    cd queues-quickstart

Installer les packages

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

Ajoutez azure-sdk-bom pour prendre une dépendance sur la dernière version de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace {bom_version_to_target} réservé 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 le boM, consultez le fichier README du Kit de développement logiciel (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 de dépendance 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. Supprimer l’instruction System.out.println("Hello, world");
  4. Ajouter 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
    }
}

Authentifiez-vous sur Azure

Les demandes d’application adressées à la plupart des services Azure doivent être autorisées. L’utilisation de la DefaultAzureCredential classe 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 les demandes adressées aux services Azure à l’aide de mots de passe, de chaînes de connexion ou d’autres informations d’identification directement. Toutefois, cette approche doit être utilisée avec précaution. Les développeurs doivent être attentifs à ne jamais exposer ces secrets dans un emplacement non sécurisé. Toute personne qui accède au mot de passe ou à la clé secrète peut s’authentifier. DefaultAzureCredential offre des avantages de gestion et de sécurité améliorés sur 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 et 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 localement, puis utiliser une identité managée une fois qu’elle a été déployée sur Azure. Aucune modification du code n’est nécessaire 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 rôle Contributeur aux données en file d’attente du stockagee pour lire et écrire des données de file d’attente. 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 en utilisant le 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, délimité au compte de stockage, pour suivre le principe du privilège 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 affecte le rôle Contributeur aux données de file d’attente de stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données de 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. Dans la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôle.

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

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

  1. Utilisez la zone de recherche pour filtrer les résultats selon le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données de file d’attente de stockage et 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 + attribuer pour accéder à la page finale, puis sélectionnez à nouveau Vérifier + attribuer pour terminer le processus.

Modèle d'objet

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

  • Compte de stockage : tout l’accès au stockage Azure est effectué via un compte de stockage. Pour plus d’informations sur les comptes de stockage, consultez vue d’ensemble du compte de stockage
  • File d’attente : une file d’attente contient un ensemble de messages. Tous les messages doivent se trouver dans une file d’attente. Notez que le nom de la file d’attente doit être en minuscules. Pour plus d’informations sur les files d’attente d’affectation de noms, consultez Files d’attente et métadonnées d’affectation de noms.
  • Message : message, dans n’importe quel format, allant jusqu’à 64 Ko. Un message peut rester dans la file d’attente pendant un maximum de 7 jours. Pour la version 2017-07-29 ou ultérieure, la durée maximale de vie peut être un nombre positif ou -1 indiquant que le message n’expire pas. Si ce paramètre est omis, la durée de vie par défaut est de sept jours.

Le diagramme suivant montre la relation entre ces ressources.

Diagramme de l’architecture de stockage de file d’attente

Utilisez les classes Java suivantes pour interagir avec ces ressources :

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

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les actions suivantes avec la bibliothèque client Azure Queue de Stockage 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 affecté 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 utiliser QueueClient pour créer et autoriser un objet DefaultAzureCredential afin d’accéder aux données de file d’attente dans le compte de stockage. DefaultAzureCredential détecte et utilise automatiquement le compte avec lequel vous vous êtes connecté à l’étape précédente.

Pour autoriser l’utilisation DefaultAzureCredential, 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 classe QueueClient, à l’aide de 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 que le trait d’union. Le nom doit également avoir une longueur de 3 à 63 caractères. Pour plus d’informations sur la nomination des files d’attente, consultez Noms 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();

Note

Les messages envoyés à l’aide de la QueueClient classe doivent être dans un format qui peut ê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

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

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

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 sendMessage méthode. Il enregistre également un SendMessageResult retourné à partir d’un appel de sendMessage. Le résultat est utilisé pour mettre à jour le message plus loin dans le programme.

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

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

Aperçu des messages dans une file d’attente

Examinez les messages dans la file d’attente en appelant la peekMessages méthode. Cette méthode récupère un ou plusieurs messages à partir de l’avant de la file d’attente, mais ne modifie pas la visibilité du message.

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

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 updateMessage méthode. Cette méthode peut modifier le délai d’expiration et le contenu de visibilité d’un message. Le contenu du message doit être une chaîne encodée UTF-8 pouvant atteindre 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));

Obtenir la longueur de la file d’attente

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

La getProperties méthode retourne plusieurs valeurs, y compris le nombre de messages actuellement dans une file d’attente. Le nombre est approximatif, car les messages peuvent être ajoutés ou supprimés après votre demande. La getApproximateMessageCount méthode 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 précédemment ajoutés en appelant la receiveMessages méthode. L’exemple de code supprime également les messages de la file d’attente après leur réception et leur traitement. Dans ce cas, le traitement affiche simplement le message sur la console.

L’application suspend l’entrée de l’utilisateur en appelant System.console().readLine(); avant de recevoir et de supprimer les messages. Vérifiez dans votre portail Azure que les ressources ont été créées correctement, avant de les supprimer. Tous les messages qui ne sont pas explicitement supprimés sont finalement visibles dans la file d’attente pour une autre chance de les traiter.

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

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 receiveMessages méthode, vous pouvez éventuellement spécifier une valeur pour maxMessages, qui est le nombre de messages à récupérer à partir de la file d’attente. La valeur par défaut est 1 message et la valeur maximale est de 32 messages. Vous pouvez également spécifier une valeur pour visibilityTimeout, qui masque les messages liés à d'autres opérations pendant le délai d'attente. 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 à l’aide de la Delete méthode.

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

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 et ajoute trois messages à une file d’attente Azure. Le code répertorie les messages de la file d’attente, puis les récupère et les supprime, avant enfin de supprimer la file d’attente.

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

mvn compile

Ensuite, générez le package.

mvn package

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

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

La sortie de l’application est similaire à 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

Lorsque 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 Enter touche pour recevoir et supprimer les messages. Lorsque vous y êtes invité, appuyez de nouveau sur la Enter touche 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 du code Java. Vous avez ensuite appris à afficher, récupérer et supprimer des messages. Enfin, vous avez appris à supprimer une file d’attente de messages.

Pour obtenir des didacticiels, des exemples, des démarrages rapides et d’autres documents, visitez :

Azure pour les développeurs cloud Java

  • Pour obtenir des exemples de code connexes utilisant des kits SDK Java version 8 déconseillées, consultez les exemples de code utilisant Java version 8.
  • Pour plus d’exemples d’applications sur Azure Queue Storage, consultez la bibliothèque cliente pour Java - exemples.
  • Last updated on