Guide pratique pour utiliser Stockage Files d’attente à partir de Python
Vue d’ensemble
Cet article présente des scénarios courants d’utilisation du service Stockage File d’attente Azure. Les scénarios traités comprennent l’insertion, la consultation rapide, la récupération 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é.
Les exemples de cet article sont écrits en Python et utilisent la bibliothèque de client Stockage File d'attente Azure pour Python. 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 :
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.
Télécharger et installer le SDK Stockage Azure pour Python
Le SDK Stockage Azure pour Python nécessite Python versions 2.7, 3.3 et ultérieures.
Effectuer l'installation via PyPi
Pour effectuer l’installation via PyPI (Python Package Index), tapez :
pip install azure-storage-queue
Notes
Si vous mettez à niveau la version 0.36 ou antérieure du SDK Stockage Azure pour Python, désinstallez l’ancien SDK à l’aide de pip uninstall azure-storage avant d’installer le dernier package.
Pour connaître les autres méthodes d'installation, consultez SDK Azure pour Python.
Copier vos informations d’identification depuis le portail Azure
Lorsque l’exemple d’application effectue une requête auprès du stockage Azure, il doit être autorisé. Pour autoriser une demande, ajoutez les informations d’identification de votre compte de stockage à l’application sous la forme d’une chaîne de connexion. Pour afficher les informations d’identification de votre compte de stockage, effectuez les étapes suivantes :
Connectez-vous au portail Azure.
Recherchez votre compte de stockage.
Dans le volet de menu du compte de stockage, sous Sécurité + réseau, sélectionnez Clés d’accès. Ici, vous pouvez afficher les clés d’accès du compte et la chaîne de connexion complète pour chaque clé.
Dans le volet Clés d’accès, sélectionnez Afficher les clés.
Dans la section clé1, recherchez la valeur Chaîne de connexion. Sélectionnez l’icône Copier dans le Presse-papiers pour copier la chaîne de connexion. Vous ajouterez la valeur de chaîne de connexion à une variable d’environnement dans la section suivante.
Configurer votre chaîne de connexion de stockage
Après avoir copié la chaîne de connexion, écrivez-la dans une variable d’environnement sur l’ordinateur local exécutant l’application. Pour définir la variable d’environnement, ouvrez une fenêtre de console et suivez les instructions pour votre système d’exploitation. Remplacez <yourconnectionstring> par votre chaîne de connexion.
setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"
Après avoir ajouté la variable d’environnement dans Windows, vous devez démarrer une nouvelle instance de la fenêtre de commande.
Redémarrer des programmes
Après avoir ajouté la variable d’environnement, redémarrez tous les programmes en cours d’exécution qui devront la lire. Par exemple, redémarrez l’environnement ou l’éditeur de développement avant de continuer.
Configuration de votre application pour accéder au stockage de files d'attente
L’objet QueueClient vous permet d’utiliser une file d’attente. Ajoutez le code suivant au début de chaque fichier Python dans lequel vous souhaitez accéder à une file d'attente Azure par programme :
from azure.storage.queue import (
QueueClient,
BinaryBase64EncodePolicy,
BinaryBase64DecodePolicy
)
import os, uuid
Le package os permet d'extraire une variable d'environnement. Le package uuid permet de générer un identificateur unique pour un nom de file d'attente.
Créer une file d’attente
La chaîne de connexion est extraite de la variable d'environnement AZURE_STORAGE_CONNECTION_STRING définie précédemment.
Le code suivant crée un objet QueueClient à l'aide de la chaîne de connexion de stockage.
# Retrieve the connection string from an environment
# variable named AZURE_STORAGE_CONNECTION_STRING
connect_str = os.getenv("AZURE_STORAGE_CONNECTION_STRING")
# Create a unique name for the queue
q_name = "queue-" + str(uuid.uuid4())
# Instantiate a QueueClient object which will
# be used to create and manipulate the queue
print("Creating queue: " + q_name)
queue_client = QueueClient.from_connection_string(connect_str, q_name)
# Create the queue
queue_client.create_queue()
Les messages de la file d’attente Azure sont stockés sous forme de texte. Si vous souhaitez stocker des données binaires, configurez les fonctions d'encodage et de décodage Base64 avant de placer un message dans la file d'attente.
Configurez les fonctions d’encodage et de décodage en Base64 lors de la création de l’objet client.
# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
conn_str=connect_str, queue_name=q_name,
message_encode_policy = BinaryBase64EncodePolicy(),
message_decode_policy = BinaryBase64DecodePolicy()
)
Insertion d'un message dans une file d'attente
Pour insérer un message dans une file d’attente, utilisez la méthode send_message.
message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)
Afficher un aperçu des messages
Vous pouvez lire les messages sans les supprimer de la file d’attente en appelant la méthode peek_messages. Par défaut, cette méthode lit un seul message.
# Peek at the first message
messages = queue_client.peek_messages()
for peeked_message in messages:
print("Peeked message: " + peeked_message.content)
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 de la tâche.
Le code suivant utilise la méthode update_message pour mettre à jour un message. Ce délai de visibilité est défini sur 0, ce qui signifie que le message s’affiche immédiatement et que le contenu est mis à jour.
messages = queue_client.receive_messages()
list_result = next(messages)
message = queue_client.update_message(
list_result.id, list_result.pop_receipt,
visibility_timeout=0, content=u'Hello World Again')
print("Updated message to: " + message.content)
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 get_queue_properties retourne les propriétés de file d’attente, y compris approximate_message_count.
properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))
Le résultat est seulement approximatif, car des messages peuvent être ajoutés ou supprimés après que le service a répondu à votre demande.
Enlever des messages d’une file d’attente
Supprimez un message d'une file d'attente en deux étapes. 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. Appelez delete_message une fois le message traité.
Lorsque vous appelez receive_messages, vous obtenez par défaut le message suivant de la file d'attente. Un message renvoyé par receive_messages 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 delete_message.
messages = queue_client.receive_messages()
for message in messages:
print("Dequeueing message: " + message.content)
queue_client.delete_message(message.id, message.pop_receipt)
Il existe deux façons de personnaliser la récupération des messages à partir d'une file d'attente. Premièrement, vous pouvez obtenir un lot de messages (jusqu'à 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.
L’exemple de code suivant utilise la méthode receive_messages pour recevoir des messages par lots. Il traite ensuite chacun des messages de chaque lot en utilisant une boucle for imbriquée. Il définit également le délai d'expiration de l'invisibilité sur cinq minutes pour chaque message.
messages = queue_client.receive_messages(messages_per_page=5, visibility_timeout=5*60)
for msg_batch in messages.by_page():
for msg in msg_batch:
print("Batch dequeue message: " + msg.content)
queue_client.delete_message(msg)
Suppression d'une file d'attente
Pour supprimer une file d’attente et tous les messages qu’elle contient, appelez la méthode delete_queue.
print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()
Conseil
Testez Microsoft Azure Storage Explorer
Microsoft Azure Storage Explorer est une application autonome et gratuite de Microsoft qui vous permet d’exploiter visuellement les données de Stockage Azure sur Windows, macOS et Linux.
Étapes suivantes
Maintenant que vous connaissez les bases du Stockage File d'attente, consultez les liens suivants pour en savoir plus.
- Informations de référence sur l’API Python Stockage File d'attente Azure
- Centre de développement Python
- Référence de l’API REST des services de stockage
Pour obtenir des exemples de code associés utilisant des Kits de développement logiciel (SDK) Python version 2 déconseillés, consultez l’article Exemples de code utilisant Python version 2.