Utilisation du stockage de files d'attente à partir de JavaHow to use Queue storage from Java

Conseil

Consultez le référentiel d’exemples de code de Stockage AzureCheck out the Azure Storage code samples repository

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.For easy-to-use end-to-end Azure Storage code samples that you can download and run, please check out our list of Azure Storage Samples.

Ce guide décrit le déroulement de scénarios courants dans le cadre de l'utilisation du service de stockage des files d'attente Azure.This guide will show you how to perform common scenarios using the Azure Queue storage service. Les exemples sont écrits en Java et utilisent le Kit de développement logiciel (SDK) Azure Storage pour Java.The samples are written in Java and use the Azure Storage SDK for Java. Les scénarios traités incluent l’insertion, la lecture furtive, la récupération et la suppression des messages de file d’attente, ainsi que la création et suppression des files d’attente.The scenarios covered include inserting, peeking, getting, and deleting queue messages, as well as creating and deleting queues. Pour plus d’informations sur les files d’attente, consultez la section Étapes suivantes.For more information on queues, see the Next steps section.

Notes

un Kit de développement logiciel (SDK) est disponible pour les développeurs qui utilisent Azure Storage sur des appareils Android.An SDK is available for developers who are using Azure Storage on Android devices. Pour plus d'informations, consultez la page Kit de développement logiciel (SDK) Azure Storage pour Android.For more information, see the Azure Storage SDK for Android.

Présentation du stockage File d’attenteWhat is Queue storage?

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.Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or 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.A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Le stockage File d’attente est couramment utilisé pour créer un backlog de travail à traiter de façon asynchrone.Queue storage is often used to create a backlog of work to process asynchronously.

Concepts du service File d’attenteQueue service concepts

Le service de File d’attente Azure contient les composants suivants :The Azure Queue service contains the following components:

Composants du service File d’attente Azure

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

    L'URL suivante désigne une file d'attente du schéma :The following URL addresses a queue in the diagram:

    http://myaccount.queue.core.windows.net/images-to-download

  • Compte de stockage : Tous les accès à Azure Storage passent par un compte de stockage.Storage Account: All access to Azure Storage is done through a storage account. Pour plus d’informations sur les comptes de stockage, consultez [Vue d’ensemble des comptes de stockage][../articles/storage/common/storage-account-overview.md].For more information about storage accounts, see [Storage account overview][../articles/storage/common/storage-account-overview.md].

  • File d’attente : Une file d’attente contient un ensemble de messages.Queue: A queue contains a set of messages. Tous les messages doivent être dans une file d’attente.All messages must be in a queue. Notez que le nom de la file d’attente doit être en minuscules.Note that the queue name must be all lowercase. 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.For information on naming queues, see Naming Queues and Metadata.

  • Message : Message dans n’importe quel format d’une taille maximale de 64 Ko.Message: A message, in any format, of up to 64 KB. La durée maximale pendant laquelle un message peut rester dans la file d’attente est de 7 jours.The maximum time that a message can remain in the queue is 7 days. 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.For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. Si ce paramètre est omis, la valeur par défaut de la durée de vie est de sept jours.If this parameter is omitted, the default time-to-live is seven days.

Créer un compte de stockage AzureCreate an Azure storage account

Le moyen le plus simple de créer votre premier compte de stockage Azure est d’utiliser le portail Azure.The easiest way to create your first Azure storage account is by using the Azure portal. Pour plus d’informations, consultez la page Créer un compte de stockage.To learn more, see Create a storage account.

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.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .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.If you prefer not to create a storage account in Azure at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Pour plus d’informations, consultez Utilisation de l’émulateur de stockage Azure pour le développement et le test.For more information, see Use the Azure Storage Emulator for Development and Testing.

Création d’une application JavaCreate a Java application

Dans ce guide, vous allez utiliser des fonctionnalités de stockage qui peuvent être exécutées dans une application Java en local, ou dans le code s'exécutant dans une application dans Azure.In this guide, you will use storage features that can be run within a Java application locally, or in code running within a web application in Azure.

Pour ce faire, vous devez installer le Kit de développement Java (JDK) et créer un compte Azure Storage dans votre abonnement Azure.To do so, you will need to install the Java Development Kit (JDK) and create an Azure storage account in your Azure subscription. Vous devez ensuite vérifier que votre système de développement répond à la configuration minimale requise et aux dépendances répertoriées dans le référentiel Kit de développement logiciel (SDK) Stockage Azure pour Java sur GitHub.Once you have done so, you will need to verify that your development system meets the minimum requirements and dependencies that are listed in the Azure Storage SDK for Java repository on GitHub. Si tel est le cas, vous pouvez suivre les instructions relatives au téléchargement et à l'installation des bibliothèques Azure Storage pour Java sur votre système à partir du référentiel.If your system meets those requirements, you can follow the instructions for downloading and installing the Azure Storage Libraries for Java on your system from that repository. Une fois ces tâches effectuées, vous pouvez créer une application Java utilisant les exemples de cet article.Once you have completed those tasks, you will be able to create a Java application that uses the examples in this article.

Configuration de votre application pour accéder au stockage de files d'attenteConfigure your application to access queue storage

Ajoutez les instructions import suivantes au début du fichier Java dans lequel vous voulez utiliser des API de stockage Azure pour accéder aux files d'attente :Add the following import statements to the top of the Java file where you want to use Azure storage APIs to access queues:

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

Configuration d’une chaîne de connexion au stockage AzureSet up an Azure storage connection string

Un client de stockage Azure utilise une chaîne de connexion de stockage pour stocker des points de terminaison et des informations d’identification permettant d’accéder aux services de gestion des données.An Azure storage client uses a storage connection string to store endpoints and credentials for accessing data management services. Lors de l’exécution dans une application cliente, vous devez spécifier la chaîne de connexion au stockage au format suivant, en indiquant le nom de votre compte de stockage et sa clé d’accès primaire, correspondant aux valeurs AccountName et AccountKey, sur le portail Azure.When running in a client application, you must provide the storage connection string in the following format, using the name of your storage account and the Primary access key for the storage account listed in the Azure portal for the AccountName and AccountKey values. Cet exemple vous montre comment déclarer un champ statique pour qu’il contienne une chaîne de connexion :This example shows how you can declare a static field to hold the connection string:

// Define the connection-string with your values.
public static final String storageConnectionString =
    "DefaultEndpointsProtocol=http;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key";

Dans une application exécutée au sein d'un rôle dans Microsoft Azure, cette chaîne peut être stockée dans le fichier de configuration de service ServiceConfiguration.cscfget elle est accessible en appelant la méthode RoleEnvironment.getConfigurationSettings .In an application running within a role in Microsoft Azure, this string can be stored in the service configuration file, ServiceConfiguration.cscfg, and can be accessed with a call to the RoleEnvironment.getConfigurationSettings method. Voici un exemple de code vous permettant d'extraire la chaîne de connexion à partir d'un élément Setting nommé StorageConnectionString dans le fichier de configuration de service :Here's an example of getting the connection string from a Setting element named StorageConnectionString in the service configuration file:

// Retrieve storage account from connection-string.
String storageConnectionString =
    RoleEnvironment.getConfigurationSettings().get("StorageConnectionString");

Les exemples ci-dessous partent du principe que vous avez utilisé l’une de ces deux méthodes pour obtenir la chaîne de connexion de stockage.The following samples assume that you have used one of these two methods to get the storage connection string.

Activation Créer une file d’attenteHow to: Create a queue

Un objet CloudQueueClient vous permet d'obtenir les objets de référence pour les files d'attente.A CloudQueueClient object lets you get reference objects for queues. Le code suivant crée un objet CloudQueueClient .The following code creates a CloudQueueClient object. (Remarque : D’autres méthodes permettent de créer des objets CloudStorageAccount. Pour plus d’informations, consultez la section CloudStorageAccount dans la page Référence du Kit de développement logiciel (SDK) du client Azure Storage.(Note: There are additional ways to create CloudStorageAccount objects; for more information, see CloudStorageAccount in the Azure Storage Client SDK Reference.)

Utilisez l'objet CloudQueueClient pour obtenir une référence pointant vers la file d'attente à utiliser.Use the CloudQueueClient object to get a reference to the queue you want to use. Si la file d'attente n'existe pas, vous pouvez la créer :You can create the queue if it doesn't exist.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

   // Create the queue client.
   CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

   // Retrieve a reference to a queue.
   CloudQueue queue = queueClient.getQueueReference("myqueue");

   // Create the queue if it doesn't already exist.
   queue.createIfNotExists();
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Ajout d'un message à une file d'attenteHow to: Add a message to a queue

Pour insérer un message dans une file d'attente existante, commencez par créer un CloudQueueMessage.To insert a message into an existing queue, first create a new CloudQueueMessage. Appelez ensuite la méthode addMessage .Next, call the addMessage method. Un CloudQueueMessage peut être créé à partir d'une chaîne (au format UTF-8) ou d'un tableau d'octets.A CloudQueueMessage can be created from either a string (in UTF-8 format) or a byte array. Voici le code qui crée une file d'attente (si elle n'existe pas) et insère le message « Hello, World ».Here is code that creates a queue (if it doesn't exist) and inserts the message "Hello, World".

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Create the queue if it doesn't already exist.
    queue.createIfNotExists();

    // Create a message and add it to the queue.
    CloudQueueMessage message = new CloudQueueMessage("Hello, World");
    queue.addMessage(message);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Lecture furtive du message suivantHow to: Peek at the next message

Vous pouvez lire furtivement le message au début de la file d'attente sans l'enlever de la file d'attente en appelant peekMessage.You can peek at the message in the front of a queue without removing it from the queue by calling peekMessage.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Peek at the next message.
    CloudQueueMessage peekedMessage = queue.peekMessage();

    // Output the message value.
    if (peekedMessage != null)
    {
      System.out.println(peekedMessage.getMessageContentAsString());
   }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Modification du contenu d'un message en file d'attenteHow to: Change the contents of a queued message

Vous pouvez modifier le contenu d'un message placé dans la file d'attente.You can change the contents of a message in-place in the queue. Si le message représente une tâche, vous pouvez utiliser cette fonctionnalité pour mettre à jour l'état de la tâche.If the message represents a work task, you could use this feature to update the status of the work task. Le code suivant met à jour le message de la file d'attente avec un nouveau contenu et ajoute 60 secondes au délai d'expiration de la visibilité.The following code updates the queue message with new contents, and sets the visibility timeout to extend another 60 seconds. L’extension du délai de visibilité enregistre l'état de la tâche associée au message et accorde une minute supplémentaire au client pour traiter le message.Extending the visibility timeout saves the state of work associated with the message, and gives the client another minute to continue working on the message. Vous pouvez utiliser cette technique pour suivre des flux de travail à plusieurs étapes sur les messages de file d'attente, sans devoir reprendre du début si une étape du traitement échoue à cause d'une défaillance matérielle ou logicielle.You could use this technique to track multi-step workflows on queue messages, without having to start over from the beginning if a processing step fails due to hardware or software failure. Normalement, vous conservez aussi un nombre de nouvelles tentatives et si le message est retenté plus de n fois, vous le supprimez.Typically, you would keep a retry count as well, and if the message is retried more than n times, you would delete it. Cela protège du déclenchement d'une erreur d'application par un message chaque fois qu'il est traité.This protects against a message that triggers an application error each time it is processed.

L'exemple de code suivant effectue une recherche dans la file d'attente de messages, recherche le premier message dont le contenu correspond à « Hello, World », modifie le contenu du message, puis se ferme.The following code sample searches through the queue of messages, locates the first message that matches "Hello, World" for the content, then modifies the message content and exits.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // The maximum number of messages that can be retrieved is 32.
    final int MAX_NUMBER_OF_MESSAGES_TO_PEEK = 32;

    // Loop through the messages in the queue.
    for (CloudQueueMessage message : queue.retrieveMessages(MAX_NUMBER_OF_MESSAGES_TO_PEEK,1,null,null))
    {
        // Check for a specific string.
        if (message.getMessageContentAsString().equals("Hello, World"))
        {
            // Modify the content of the first matching message.
            message.setMessageContent("Updated contents.");
            // Set it to be visible in 30 seconds.
            EnumSet<MessageUpdateFields> updateFields =
                EnumSet.of(MessageUpdateFields.CONTENT,
                MessageUpdateFields.VISIBILITY);
            // Update the message.
            queue.updateMessage(message, 30, updateFields, null, null);
            break;
        }
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

L'exemple de code suivant met simplement à jour le premier message visible dans la file d'attente.Alternatively, the following code sample updates just the first visible message on the queue.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve the first visible message in the queue.
    CloudQueueMessage message = queue.retrieveMessage();

    if (message != null)
    {
        // Modify the message content.
        message.setMessageContent("Updated contents.");
        // Set it to be visible in 60 seconds.
        EnumSet<MessageUpdateFields> updateFields =
            EnumSet.of(MessageUpdateFields.CONTENT,
            MessageUpdateFields.VISIBILITY);
        // Update the message.
        queue.updateMessage(message, 60, updateFields, null, null);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Obtention de la longueur de la file d'attenteHow to: Get the queue length

Vous pouvez obtenir une estimation du nombre de messages dans une file d'attente.You can get an estimate of the number of messages in a queue. La méthode downloadAttributes demande au service de File d'attente plusieurs valeurs actives, y compris le nombre de messages dans une file d'attente.The downloadAttributes method asks the Queue service for several current values, including a count of how many messages are in a queue. Ce nombre est approximatif étant donné que des messages peuvent être ajoutés ou supprimés une fois que le service de File d'attente a répondu à votre demande.The count is only approximate because messages can be added or removed after the Queue service responds to your request. La méthode getApproximateMessageCount renvoie la dernière valeur extraite par l’appel à downloadAttributes, sans appeler le service de File d’attente.The getApproximateMessageCount method returns the last value retrieved by the call to downloadAttributes, without calling the Queue service.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
       CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

   // Download the approximate message count from the server.
    queue.downloadAttributes();

    // Retrieve the newly cached approximate message count.
    long cachedMessageCount = queue.getApproximateMessageCount();

    // Display the queue length.
    System.out.println(String.format("Queue length: %d", cachedMessageCount));
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Suppression du message suivant de la file d’attenteHow to: Dequeue the next message

Votre code enlève un message d'une file d'attente en deux étapes.Your code dequeues a message from a queue in two steps. Lorsque vous appelez retrieveMessage, vous obtenez le message suivant dans une file d'attente.When you call retrieveMessage, you get the next message in a queue. Un message renvoyé par retrieveMessage devient invisible de tout autre code lisant les messages de cette file d'attente.A message returned from retrieveMessage becomes invisible to any other code reading messages from this queue. Par défaut, ce message reste invisible pendant 30 secondes.By default, this message stays invisible for 30 seconds. Pour finaliser la suppression du message de la file d'attente, vous devez aussi appeler deleteMessage.To finish removing the message from the queue, you must also call deleteMessage. Ce processus de suppression d'un message en deux étapes garantit que, si votre code ne parvient pas à traiter un message à cause d'une défaillance matérielle ou logicielle, une autre instance de votre code peut obtenir le même message et réessayer.This two-step process of removing a message assures that if your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. Votre code appelle deleteMessage juste après le traitement du message.Your code calls deleteMessage right after the message has been processed.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve the first visible message in the queue.
    CloudQueueMessage retrievedMessage = queue.retrieveMessage();

    if (retrievedMessage != null)
    {
        // Process the message in less than 30 seconds, and then delete the message.
        queue.deleteMessage(retrievedMessage);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Options supplémentaires pour la suppression des messages dans la file d'attenteAdditional options for dequeuing messages

Il existe deux façons de personnaliser la récupération des messages à partir d'une file d'attente.There are two ways you can customize message retrieval from a queue. Premièrement, vous pouvez obtenir un lot de messages (jusqu'à 32).First, you can get a batch of messages (up to 32). Deuxièmement, vous pouvez définir 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.Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message.

L'exemple de code suivant utilise la méthode retrieveMessages pour obtenir 20 messages en un appel.The following code example uses the retrieveMessages method to get 20 messages in one call. Ensuite, il traite chaque message à l'aide d'une boucle for .Then it processes each message using a for loop. Il définit également le délai d'expiration de l'invisibilité sur cinq minutes (300 secondes) pour chaque message.It also sets the invisibility timeout to five minutes (300 seconds) for each message. Le délai de cinq minutes démarre en même temps pour tous les messages, donc une fois les cinq minutes écoulées après l'appel de retrieveMessages, tous les messages n'ayant pas été supprimés redeviennent visibles.The five minutes start for all messages at the same time, so when five minutes have passed since the call to retrieveMessages, any messages that have not been deleted will become visible again.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
    for (CloudQueueMessage message : queue.retrieveMessages(20, 300, null, null)) {
        // Do processing for all messages in less than 5 minutes,
        // deleting each message after processing.
        queue.deleteMessage(message);
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Répertorier les files d’attenteHow to: List the queues

Pour obtenir la liste des files d’attente en cours, appelez la méthode CloudQueueClient.listQueues() , qui renvoie une collection d’objets CloudQueue.To obtain a list of the current queues, call the CloudQueueClient.listQueues() method, which will return a collection of CloudQueue objects.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient =
        storageAccount.createCloudQueueClient();

    // Loop through the collection of queues.
    for (CloudQueue queue : queueClient.listQueues())
    {
        // Output each queue name.
        System.out.println(queue.getName());
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Activation Suppression d'une file d'attenteHow to: Delete a queue

Pour supprimer une file d’attente et tous les messages qu’elle contient, appelez la méthode deleteIfExists sur l’objet CloudQueue.To delete a queue and all the messages contained in it, call the deleteIfExists method on the CloudQueue object.

try
{
    // Retrieve storage account from connection-string.
    CloudStorageAccount storageAccount =
        CloudStorageAccount.parse(storageConnectionString);

    // Create the queue client.
    CloudQueueClient queueClient = storageAccount.createCloudQueueClient();

    // Retrieve a reference to a queue.
    CloudQueue queue = queueClient.getQueueReference("myqueue");

    // Delete the queue if it exists.
    queue.deleteIfExists();
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Étapes suivantesNext steps

Maintenant que vous connaissez les bases du stockage des files d'attente, consultez les liens suivants pour apprendre à exécuter les tâches de stockage plus complexes.Now that you've learned the basics of queue storage, follow these links to learn about more complex storage tasks.