Partager via


Utilisation du Stockage File d’attente à partir de Java

Vue d’ensemble

Ce guide explique comment écrire du code pour des scénarios courants à l’aide du service Stockage File d’attente Azure. Les exemples sont écrits en Java et utilisent le Kit de développement logiciel (SDK) Azure Storage pour Java. Les scénarios comprennent l'insertion, la consultation, l'obtention et la suppression de messages de la file d'attente. Le code de création et de suppression de files d'attente est également abordé. Pour plus d’informations sur les files d’attente, consultez la section Étapes suivantes.

Présentation du stockage File d’attente

Les files d’attente de stockage Azure sont un service permettant de stocker un grand nombre de messages accessibles depuis n’importe où dans le monde via des appels authentifiés avec HTTP ou HTTPS. Un simple message de file d’attente peut avoir une taille de 64 Ko et une file d’attente peut contenir des millions de messages, jusqu’à la limite de capacité totale d’un compte de stockage. Le stockage File d’attente est couramment utilisé pour créer un backlog de travail à traiter de façon asynchrone.

Concepts du service File d’attente

Le service de File d’attente Azure contient les composants suivants :

Composants du service File d’attente Azure

  • 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. La durée maximale pendant laquelle un message peut rester dans la file d’attente est 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.

  • Format d’URL : les files d’attente sont adressables à l’aide du format d’URL suivant : http://<storage account>.queue.core.windows.net/<queue>

    L'URL suivante désigne une file d'attente du schéma :

    http://myaccount.queue.core.windows.net/incoming-orders

Créer un compte de stockage Azure

Le moyen le plus simple de créer votre premier compte de stockage Azure est d’utiliser le portail Azure. Pour plus d’informations, consultez la page Créer un compte de stockage.

Vous pouvez également créer un compte de stockage Azure à l’aide d’Azure PowerShell, de l’interface de ligne de commande Azure ou du fournisseur de ressources de stockage Azure pour .NET.

Si vous préférez ne pas créer de compte de stockage dans Azure pour le moment, vous avez la possibilité d’utiliser l’émulateur de stockage Azure pour exécuter et tester votre code dans un environnement local. Pour plus d’informations, consultez Utiliser l’émulateur Azurite à des fins de développement local pour Stockage Azure.

Création d’une application Java

Commencez par vérifier que votre système de développement répond aux prérequis listés dans Bibliothèque de client du Stockage File d’attente Azure pour Java v12.

Pour créer une application Java nommée queues-how-to-v12 :

  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-how-to-v12. Tapez la commande mvn suivante pour créer un projet Java « hello world ».

     mvn archetype:generate \
         --define interactiveMode=n \
         --define groupId=com.queues.howto \
         --define artifactId=queues-howto-v12 \
         --define archetypeArtifactId=maven-archetype-quickstart \
         --define archetypeVersion=1.4
    
    mvn archetype:generate `
        --define interactiveMode=n `
        --define groupId=com.queues.howto `
        --define artifactId=queues-howto-v12 `
        --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.howto
    [INFO] Parameter: artifactId, Value: queues-howto-v12
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.howto
    [INFO] Parameter: packageInPathFormat, Value: com/queues/howto
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.howto
    [INFO] Parameter: groupId, Value: com.queues.howto
    [INFO] Parameter: artifactId, Value: queues-howto-v12
    [INFO] Project created from Archetype in dir: C:\queues\queues-howto-v12
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  6.775 s
    [INFO] Finished at: 2020-08-17T15:27:31-07:00
    [INFO] ------------------------------------------------------------------------
    
  3. Basculez vers le répertoire queues-howto-v12 créé.

    cd queues-howto-v12
    

Installer le package

Ouvrez le fichier pom.xml dans votre éditeur de texte. Ajoutez l’élément dépendance suivant au groupe de dépendances.

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

Configuration de votre application pour accéder au stockage de files d'attente

Ajoutez les instructions d’importation suivantes au début du fichier Java dans lequel vous voulez utiliser les API Stockage Azure pour accéder aux files d’attente :

// Include the following imports to use queue APIs
import com.azure.core.util.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;

Configurer une chaîne de connexion au stockage Azure

Un client Stockage Azure utilise une chaîne de connexion de stockage pour accéder aux services de gestion des données. Procurez-vous le nom et la clé d’accès principale de votre compte de stockage sur le portail Azure. Utilisez-les comme valeurs AccountName et AccountKey dans la chaîne de connexion. Cet exemple vous montre comment déclarer un champ statique pour qu’il contienne une chaîne de connexion :

// Define the connection-string with your values
final String connectStr = 
    "DefaultEndpointsProtocol=https;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key";

Les exemples ci-dessous partent du principe que vous avez utilisé un objet String contenant la chaîne de connexion de stockage.

Procédure : Créer une file d’attente

Un objet QueueClient contient les opérations permettant d'interagir avec une file d'attente. Le code suivant crée un objet QueueClient. Utilisez l'objet QueueClient pour créer la file d'attente que vous souhaitez utiliser.

public static String createQueue(String connectStr)
{
    try
    {
        // Create a unique name for the queue
        String queueName = "queue-" + java.util.UUID.randomUUID();

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

        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queue = new QueueClientBuilder()
                                .connectionString(connectStr)
                                .queueName(queueName)
                                .buildClient();

        // Create the queue
        queue.create();
        return queue.getQueueName();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println("Error code: " + e.getErrorCode() + "Message: " + e.getMessage());
        return null;
    }
}

Procédure : Ajout d'un message à une file d'attente

Pour insérer un message dans une file d'attente existante, appelez la méthode sendMessage. Un message peut être une chaîne (au format UTF-8) ou un tableau d'octets. Le code suivant envoie un message de type chaîne dans la file d'attente.

public static void addQueueMessage
    (String connectStr, String queueName, String messageText)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Adding message to the queue: " + messageText);

        // Add a message to the queue
        queueClient.sendMessage(messageText);
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : Lecture furtive du message suivant

Vous pouvez lire furtivement le message au début de la file d’attente sans le retirer de la file d’attente en appelant peekMessage.

public static void peekQueueMessage
    (String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Peek at the first message
        PeekedMessageItem peekedMessageItem = queueClient.peekMessage();
        System.out.println("Peeked message: " + peekedMessageItem.getMessageText());
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : Modification du contenu d'un message en file d'attente

Vous pouvez modifier le contenu d'un message placé dans la file d'attente. Si le message représente une tâche, vous pouvez utiliser cette fonctionnalité pour mettre à jour l'état. Le code suivant met à jour un message de la file d'attente avec un nouveau contenu et ajoute 30 secondes au délai d'expiration de la visibilité. Grâce à la prolongation du délai d'expiration de la visibilité, le client dispose de 30 secondes supplémentaires pour continuer à travailler sur le message. Vous pouvez également définir un nombre de nouvelles tentatives. Au bout de n nouvelles tentatives, le message sera supprimé. Ce scénario protège du déclenchement d'une erreur d'application par un message chaque fois qu'il est traité.

L'exemple de code suivant effectue une recherche dans la file d'attente des messages, recherche le premier message dont le contenu correspond à une chaîne de recherche, modifie le contenu du message, puis se ferme.

public static void updateQueueMessage
    (String connectStr, String queueName,
    String searchString, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 32
        final int MAX_MESSAGES = 32;

        // Iterate through the queue messages
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES))
        {
            // Check for a specific string
            if (message.getMessageText().equals(searchString))
            {
                // Update the message to be visible in 30 seconds
                queueClient.updateMessage(message.getMessageId(),
                                          message.getPopReceipt(),
                                          updatedContents,
                                          Duration.ofSeconds(30));
                System.out.println(
                    String.format("Found message: \'%s\' and updated it to \'%s\'",
                                    searchString,
                                    updatedContents)
                                  );
                break;
            }
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

L'exemple de code suivant met simplement à jour le premier message visible dans la file d'attente.

public static void updateFirstQueueMessage
    (String connectStr, String queueName, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            // Update the message to be visible in 30 seconds
            UpdateMessageResult result = queueClient.updateMessage(message.getMessageId(),
                                                                   message.getPopReceipt(),
                                                                   updatedContents,
                                                                   Duration.ofSeconds(30));
            System.out.println("Updated the first message with the receipt: " +
                    result.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : 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.

public static void getQueueLength(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

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

        System.out.println(String.format("Queue length: %d", messageCount));
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : Suppression du message suivant de la file d’attente

Votre code enlève un message d'une file d'attente en deux étapes. Lorsque vous appelez receiveMessage, vous obtenez le message suivant dans une file d'attente. Un message renvoyé par receiveMessage devient invisible par les autres codes lisant les messages de cette file d'attente. Par défaut, ce message reste invisible pendant 30 secondes. Pour finaliser la suppression du message de la file d’attente, vous devez aussi appeler deleteMessage. Si votre code ne parvient pas à traiter un message, ce processus en deux étapes vous permet de récupérer le même message et de réessayer. Votre code appelle deleteMessage juste après le traitement du message.

public static void dequeueMessage(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            System.out.println("Dequeing message: " + message.getMessageText());

            // Delete the message
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
        else
        {
            System.out.println("No visible messages in queue");
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Options supplémentaires pour la suppression des messages dans la file d'attente

Il existe deux façons de personnaliser l'extraction des messages à partir d'une file d'attente. Premièrement, procurez-vous un lot de messages (jusqu'à 32). Deuxièmement, définissez un délai d'expiration de l'invisibilité plus long ou plus court afin d'accorder à votre code plus ou moins de temps pour traiter complètement chaque message.

L'exemple de code suivant utilise la méthode receiveMessages pour obtenir 20 messages en un appel. Ensuite, il traite chaque message à l'aide d'une boucle for. Il définit également le délai d'expiration de l'invisibilité sur cinq minutes (300 secondes) pour chaque message. Le délai d'expiration démarre pour tous les messages en même temps. Lorsque cinq minutes se sont écoulées depuis l'appel à receiveMessages, tous les messages non supprimés redeviennent visibles.

public static void dequeueMessages(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 20
        final int MAX_MESSAGES = 20;

        // Retrieve 20 messages from the queue with a
        // visibility timeout of 300 seconds (5 minutes)
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES,
                Duration.ofSeconds(300), Duration.ofSeconds(1), new Context("key1", "value1")))
        {
            // Do processing for all messages in less than 5 minutes,
            // deleting each message after processing.
            System.out.println("Dequeing message: " + message.getMessageText());
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : Répertorier les files d’attente

Pour obtenir la liste des files d’attente en cours, appelez la méthode QueueServiceClient.listQueues() , qui renvoie une collection d’objets QueueItem.

public static void listQueues(String connectStr)
{
    try
    {
        // Instantiate a QueueServiceClient which will be
        // used to list the queues
        QueueServiceClient queueServiceClient = new QueueServiceClientBuilder()
                                    .connectionString(connectStr)
                                    .buildClient();

        // Loop through the collection of queues.
        for (QueueItem queue : queueServiceClient.listQueues())
        {
            // Output each queue name.
            System.out.println(queue.getName());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Procédure : Suppression d'une file d'attente

Pour supprimer une file d’attente et tous les messages qu’elle contient, appelez la méthode delete dans l’objet QueueClient.

public static void deleteMessageQueue(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Deleting queue: " + queueClient.getQueueName());

        // Delete the queue
        queueClient.delete();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Conseil

Consultez le référentiel d’exemples de code de Stockage Azure

Pour des exemples de code Stockage Azure de bout en bout faciles à utiliser que vous pouvez télécharger et exécuter, consultez notre liste Exemples Stockage Azure.

Étapes suivantes

Maintenant que vous connaissez les bases du stockage file d’attente, consultez les liens suivants pour apprendre à exécuter les tâches de stockage plus complexes.

Pour obtenir des exemples de code associés utilisant des Kits de développement logiciel (SDK) Java version 8 déconseillés, consultez les Exemples de code utilisant Java version 8.