Partager via

Guide pratique pour utiliser Stockage File d’attente à partir de PowerShell

  • Article

Le Stockage File d’attente est un service permettant de stocker un grand nombre de messages accessibles partout dans le monde via HTTP ou HTTPS. Pour plus d’informations, consultez Présentation du Stockage File d’attente. Ce guide pratique décrit les opérations courantes liées au Stockage File d’attente. Vous allez apprendre à effectuer les actions suivantes :

  • Créer une file d’attente
  • Récupérer une file d’attente
  • Ajouter des messages
  • Récupérer des messages
  • Supprimer un message
  • Suppression d'une file d'attente

Ce guide pratique nécessite le module Azure PowerShell (Az) v12.0.0. Exécutez Get-Module -ListAvailable Az pour vérifier la version installée. Si vous devez effectuer une mise à niveau, consultez Installer le module Azure PowerShell.

Il n’existe aucune applet de commande PowerShell pour le plan de données des files d’attente. Pour effectuer des opérations de plan de données comme l’ajout, la lecture et la suppression d’un message, vous devez utiliser la bibliothèque cliente de stockage .NET exposée dans PowerShell. Vous créez un objet de message et vous pouvez alors utiliser des commandes comme AddMessage pour effectuer des opérations sur ce message. Cet article vous explique comment procéder.

Notes

Nous vous recommandons d’utiliser le module Azure Az PowerShell pour interagir avec Azure. Pour commencer, consultez Installer Azure PowerShell. Pour savoir comment migrer vers le module Az PowerShell, consultez Migrer Azure PowerShell depuis AzureRM vers Az.

Connexion à Azure

Connectez-vous à votre abonnement Azure avec la commande Connect-AzAccount et suivez les instructions à l’écran. Si nécessaire, vous pouvez spécifier un abonnement en ajoutant les paramètres TenantId et Subscription, et en incluant les valeurs respectives.

Connect-AzAccount

Récupérer la liste des régions

Si vous ne savez pas quelle région utiliser, vous pouvez lister les régions disponibles à l’aide de la cmdlet Get-AzLocation, comme indiqué dans l’exemple fourni. Une fois la liste affichée, choisissez une région, puis stockez-la dans la variable location pour une utilisation future. Les exemples de cet exercice utilisent la région eastus.

Get-AzLocation | Select-Object Location
$location = "eastus"

Créer un groupe de ressources

Un groupe de ressources Azure est un conteneur logique dans lequel les ressources Azure sont déployées et gérées. Choisissez un nom pour votre groupe de ressources, puis stockez-le dans la variable resourceGroup pour une utilisation future. L’exemple suivant utilise le nom howtoqueuesrg.

Créez un groupe de ressources en appelant la cmdlet New-AzResourceGroup, et en fournissant le nom et la région au paramètre ResourceGroupName, comme indiqué.

$resourceGroup = "howtoqueuesrg"
New-AzResourceGroup -ResourceGroupName $resourceGroup -Location $location

Créez un compte de stockage.

Un compte Stockage Azure est une ressource au nom unique, qui contient tous vos objets de données sous forme d’objets blob, de fichiers, de files d’attente et de tables.

Choisissez un nom pour votre compte de stockage, puis stockez-le dans la variable storageAccountName pour une utilisation future. L’exemple suivant utilise le nom howtoqueuestorage.

Créez ensuite un compte de stockage universel standard avec une fonctionnalité de stockage localement redondant (LRS) en utilisant la cmdlet New-AzStorageAccount. Enfin, définissez le contexte du compte de stockage, en l’enregistrant dans la variable ctx. Le fait de référencer le contexte avec la variable vous permet d’effectuer des opérations sur un compte de stockage sans avoir à fournir à plusieurs reprises des informations d’identification.

$storageAccountName = "howtoqueuestorage"

$storageAccount = New-AzStorageAccount -ResourceGroupName $resourceGroup `
  -Name $storageAccountName `
  -Location $location `
  -SkuName Standard_LRS

$ctx = $storageAccount.Context

Créer une file d’attente

Tout d’abord, choisissez un nom pour votre compte de stockage, puis stockez-le dans la variable queueName. L’exemple suivant utilise le nom howtoqueuestorage. Créez ensuite une file d’attente en utilisant la cmdlet New-AzStorageQueue, puis en passant les variables queueName et ctx aux paramètres Name et Context, comme indiqué.

$queueName = "howtoqueue"
$queue = New-AzStorageQueue -Name $queueName -Context $ctx

Pour plus d’informations sur les conventions de nommage qui s’appliquent au service Stockage File d’attente Azure, consultez Affectation de noms pour les files d’attente et les métadonnées.

Récupérer une file d’attente

Vous pouvez utiliser la cmdlet Get-AzStorageQueue pour récupérer une file d’attente spécifique ou une liste de toutes les files d’attente d’un compte de stockage. Les exemples suivants montrent comment récupérer toutes les files d’attente en utilisant la cmdlet Get-AzStorageQueue, et comment spécifier une file d’attente à l’aide du paramètre Name.

# Retrieve all queues and show their names
Get-AzStorageQueue -Context $ctx | Select-Object Name

# Retrieve a specific queue
$queue = Get-AzStorageQueue -Name $queueName -Context $ctx

# Show the properties of the queue
$queue

Ajouter des messages à une file d’attente

Les opérations qui ont un impact sur les messages d’une file d’attente utilisent la bibliothèque de client de stockage .NET, exposée dans PowerShell. Pour ajouter un message à une file d’attente, passez votre message sous forme de chaîne à la méthode SendMessage de la classe QueueClient.

Votre chaîne de message doit être au format UTF-8.

L’exemple suivant montre comment ajouter des messages à votre file d’attente.

# Create a new message using a constructor of the CloudQueueMessage class
$queueMessage = "This is message 1"

# Add a new message to the queue
$queue.QueueClient.AddMessageAsync($queueMessage)

# Add two more messages to the queue
$queueMessages = @("This is message 2","This is message 3")
$queueMessages | foreach {$queue.QueueClient.AddMessageAsync($_)}

Si vous utilisez l’Explorateur Stockage Azure, vous pouvez vous connecter à votre compte Azure et afficher les files d’attente dans le compte de stockage, puis en explorer une au niveau du détail pour afficher les messages qu’elle contient.

Récupérer les messages d’une file d’attente

Bien que cela ne soit pas toujours garanti, les messages sont récupérés à partir d’une file d’attente par ordre du premier entré, premier sorti dans la mesure du possible.

Selon votre cas d’usage, vous pouvez récupérer un ou plusieurs messages à partir d’une file d’attente. Vous pouvez également modifier la visibilité des messages, en autorisant ou en empêchant d’autres processus d’accéder au même message.

Il existe deux façons de récupérer des messages à partir d’une file d’attente :

  • Réception : la récupération d’un message à l’aide de Receive l’enlève de la file d’attente, et incrémente sa propriété DequeueCount. À moins qu’un message ne soit supprimé, il est réinséré dans la file d’attente pour être à nouveau traité.
  • Aperçu : la récupération d’un message à l’aide de Peek vous permet d’avoir un « aperçu » des messages de la file d’attente. Peek n’enlève pas le message de la file d’attente, et n’incrémente pas sa propriété DequeueCount.

Recevoir des messages

Quand vous lisez un message dans une file d’attente à l’aide d’une méthode telle que ReceiveMessage, le message est temporairement enlevé de la file d’attente et devient temporairement invisible pour les autres processus. Ce délai d’expiration de visibilité définit la durée pendant laquelle le message reste invisible. Le délai d’expiration de visibilité par défaut est de 30 secondes.

Si le message n’est pas traité avant la fin du délai d’expiration de visibilité, sa propriété DequeueCount est incrémentée, et il est réinséré à la fin de la file d’attente. La réinsertion du même message permet de garantir qu’un autre processus peut récupérer ce message, et réessayer.

L’exemple suivant affecte 10 secondes à la variable invisibleTimeout, puis lit deux messages dans la file d’attente.

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Read the message from the queue, then show the contents of the message. 
# Read the next message, too.
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queueMessage.Value
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queueMessage.Value

Vous pouvez récupérer plusieurs messages à la fois dans la file d’attente en utilisant la méthode ReceiveMessages, et en passant une valeur entière pour spécifier le nombre maximal de messages à retourner.

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Read the messages from the queue, then show the contents of the messages.
$queueMessage = $queue.QueueClient.ReceiveMessages(5,$visibilityTimeout)
$queueMessage.Value

Afficher un aperçu des messages

Pour les cas d’usage pouvant impliquer des files d’attente partagées ou l’aperçu des messages sans en modifier la visibilité, vous pouvez utiliser les méthodes PeekMessage et PeekMessages. Comme dans l’exemple ReceiveMessages précédent, vous pouvez afficher l’aperçu de plusieurs messages à la fois en passant une valeur entière pour spécifier le nombre maximal de messages.

Les exemples suivants utilisent les méthodes PeekMessage et PeekMessages pour récupérer les messages à partir d’une file d’attente.

# Read the message from the queue, then show the contents of the message. 
$queueMessage = $queue.QueueClient.PeekMessage()
$queueMessage.Value

# Read the next four messages, then show the contents of the messages.
$queueMessage = $queue.QueueClient.PeekMessages(4)
$queueMessage.Value

Supprimer des messages d’une file d’attente

Pour éviter toute suppression accidentelle, les propriétés MessageId et PopReceipt doivent être fournies avant la suppression définitive d’un message. En raison de cet impératif, il est plus facile de supprimer un message via un processus en deux étapes.

Tout d’abord, vous devez extraire le message suivant de la file d’attente en appelant les méthodes ReceiveMessage ou ReceiveMessages. Pour terminer la suppression du message dans la file d’attente, passez les valeurs obtenues à partir du message à la méthode DeleteMessage.

Ce processus est illustré dans les exemples suivants.

# Set the amount of time you want to entry to be invisible after read from the queue
# If it is not deleted by the end of this time, it will show up in the queue again
$visibilityTimeout = [System.TimeSpan]::FromSeconds(10)

# Receive one message from the queue, then delete the message. 
$queueMessage = $queue.QueueClient.ReceiveMessage($visibilityTimeout)
$queue.QueueClient.DeleteMessage($queueMessage.Value.MessageId, $queueMessage.Value.PopReceipt)

# Receive four message from the queue, then delete the messages. 
$queueMessage = $queue.QueueClient.ReceiveMessages(4,$visibilityTimeout)
$queueMessage.Value | foreach { $queue.QueueClient.DeleteMessage($_.MessageId, $_.PopReceipt)}

Suppression d'une file d'attente

Pour supprimer une file d’attente et tous les messages qu’elle contient, appelez la méthode Delete de la classe QueueClient. L’exemple suivant montre comment supprimer la file d’attente spécifique utilisée dans cet exercice.

# Delete the queue
Remove-AzStorageQueue -Name $queueName -Context $ctx

Nettoyer les ressources

Supprimez le groupe de ressources pour supprimer tous les types de ressources créés dans cet exercice. Dans le cas présent, le compte de stockage et le groupe de ressources lui-même sont également supprimés.

Remove-AzResourceGroup -Name $resourceGroup

Étapes suivantes

Ce guide pratique vous a présenté les bases de la gestion Stockage File d’attente avec PowerShell. Vous avez notamment appris à effectuer les tâches suivantes :

  • Créer une file d’attente
  • Récupérer une file d’attente
  • Ajouter des messages
  • Lire les messages
  • Supprimer des messages
  • Suppression d'une file d'attente

Applets de commande de stockage Microsoft Azure PowerShell

Explorateur Stockage Microsoft Azure

  • 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.