Como usar o Armazenamento de Filas do Azure a partir do PowerShell

O Armazenamento de Filas do Azure é um serviço para armazenamento de um grande número de mensagens que podem ser acessadas de qualquer lugar do mundo por meio de HTTP ou HTTPS. Para obter informações detalhadas, confira Introdução ao Armazenamento de Filas do Azure. Este artigo de instruções abrange operações comuns de Armazenamento de Filas. Você aprenderá como:

Este guia de instruções exige o módulo (Az) v12.0.0 do Azure PowerShell. Execute Get-Module -ListAvailable Az para encontrar a versão atualmente instalada. Se você precisa atualizar, consulte Instalar o módulo do Azure PowerShell.

Não há nenhum cmdlet do PowerShell para o plano de dados para filas. Para executar os dados de operações do plano, como adicionar uma mensagem, ler uma mensagem e excluir uma mensagem, você deverá usar a biblioteca de cliente de armazenamento do .NET da forma como ela é exposta no PowerShell. Você cria um objeto de mensagem e então pode usar comandos como AddMessage para executar operações nessa mensagem. Este artigo mostra como fazer isso.

Entrar no Azure

Entre na sua assinatura do Azure com o comando Connect-AzAccount e siga as instruções na tela. Se necessário, você pode especificar uma assinatura adicionando os parâmetros TenantId e Subscription, e incluindo os respectivos valores.

Connect-AzAccount

Recuperar uma lista de locais

Se você não sabe qual localização deseja usar, você pode listar as localizações disponíveis usando o cmdlet Get-AzLocation, conforme mostrado no exemplo fornecido. Depois que a lista for exibida, escolha um local e armazene-o na variável location para uso futuro. Os exemplos neste exercício usam o local eastus.

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

Criar um grupo de recursos

Um grupo de recursos do Azure é um contêiner lógico no qual os recursos do Azure são implantados e gerenciados. Escolha um nome para o grupo de recursos e armazene-o na variável resourceGroup para uso futuro. Este exemplo usa o nome howtoqueuesrg.

Crie um grupo de recursos chamando o cmdlet New-AzResourceGroup e fornecendo o nome e o local para o parâmetro ResourceGroupName, conforme mostrado.

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

Criar uma conta de armazenamento

Uma conta de armazenamento do Azure é um recurso nomeado exclusivamente que contém todos os objetos de dados como blobs, arquivos, filas e tabelas.

Escolha um nome para sua conta de armazenamento e armazene-o na variável storageAccountName para uso futuro. Este exemplo usa o nome howtoqueuestorage.

Em seguida, crie uma conta de armazenamento padrão para uso geral com o LRS (armazenamento com redundância local) usando o cmdlet New-AzStorageAccount. Por fim, defina o contexto da conta de armazenamento que define a conta de armazenamento, salvando-a na variável ctx. Fazer referência ao contexto com a variável permite que você execute operações em uma conta de armazenamento, sem fornecer credenciais repetidamente.

$storageAccountName = "howtoqueuestorage"

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

$ctx = $storageAccount.Context

Criar uma fila

Primeiro, escolha um nome para sua conta de armazenamento e armazene-o na variável queueName. Este exemplo usa o nome howtoqueuestorage. Em seguida, crie uma fila usando o cmdlet New-AzStorageQueue e passe as variáveis queueName e ctx para os parâmetros Name e Context, conforme mostrado.

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

Para obter informações sobre convenções de nomenclatura do Armazenamento de Filas do Azure, confira Nomear filas e metadados.

Recuperar uma fila

Você pode usar o cmdlet Get-AzStorageQueue para recuperar uma fila específica ou uma lista de todas as filas em uma conta de armazenamento. Os exemplos a seguir demonstram como recuperar todas as filas usando o cmdlet Get-AzStorageQueue e como especificar uma fila usando o parâmetro 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

Adicionar mensagens a uma fila

As operações que afetam as mensagens em uma fila usam a biblioteca de cliente de armazenamento do .NET como exposta no PowerShell. Para adicionar uma mensagem a uma fila, passe a mensagem como uma cadeia de caracteres para o método QueueClient da classe SendMessage.

A cadeia de caracteres de mensagem deve estar no formato UTF-8.

O exemplo a seguir demonstra como adicionar mensagens à sua fila.

# 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($_)}

Se você usar o Gerenciador de Armazenamento do Azure, poderá se conectar à sua conta do Azure e exibir as filas na conta de armazenamento e fazer uma busca detalhada em uma fila para exibir as mensagens na fila.

Recuperar mensagens de uma fila

Embora nem sempre seja garantido, as mensagens são recuperadas de uma fila na ordem de melhor tentativa e primeira a entrar, primeiro a sair.

Dependendo do caso de uso, você pode recuperar uma ou mais mensagens de uma fila. Você também pode modificar a visibilidade das mensagens, permitindo ou impedindo que outros processos acessem a mesma mensagem.

Há duas maneiras de recuperar mensagens de uma fila:

• Receber: recuperar uma mensagem usando o Receive remove a mensagem da fila e incrementa a propriedade DequeueCount. A menos que uma mensagem seja excluída, ela será reinserida na fila para ser processada novamente.
• Espiar: recuperar uma mensagem usando o Peek permite que você "visualize" as mensagens da fila. Peek não remove a mensagem da fila nem incrementa a propriedade DequeueCount.

Receber mensagens

Quando você lê uma mensagem de uma fila usando um método como ReceiveMessage, a mensagem é desativada temporariamente e torna-se invisível temporariamente para outros processos. Esse tempo limite de visibilidade define por quanto tempo a mensagem permanecerá invisível. O tempo limite de visibilidade padrão é de 30 segundos.

Se a mensagem não for processada antes que o tempo limite de visibilidade expire, a propriedade DequeueCount será incrementada e reinserida no final da fila. Reinserir a mesma mensagem garante que outro processo possa recuperar a mesma mensagem e tentar novamente.

O exemplo a seguir define a variável invisibleTimeout como 10 segundos e lê duas mensagens da fila.

# 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

Você pode recuperar várias mensagens da fila simultaneamente usando o método ReceiveMessages e passando um valor inteiro para especificar o número máximo de mensagens a serem retornadas.

# 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

Espiar mensagens

Para casos de uso que podem envolver filas compartilhadas ou visualização de mensagens sem alterar a visibilidade, você pode usar os métodos PeekMessage e PeekMessages. Assim como no exemplo anterior ReceiveMessages, várias mensagens podem ser espiadas simultaneamente passando um valor inteiro para especificar o número máximo de mensagens.

Os exemplos a seguir usam os métodos PeekMessage e PeekMessages para recuperar mensagens de uma fila.

# 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

Excluir mensagens de uma fila

Para evitar a exclusão acidental, as propriedades MessageId e PopReceipt devem ser fornecidas antes de excluir permanentemente uma mensagem. Devido a esse requisito, é mais fácil excluir uma mensagem usando um processo de duas etapas.

Primeiro, busque a próxima mensagem na fila chamando os métodos ReceiveMessage ou ReceiveMessages. Para concluir a remoção da mensagem da fila, passe os valores obtidos da mensagem para o método DeleteMessage.

Esse processo é ilustrado nos exemplos a seguir.

# 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)}

Excluir uma fila

Para excluir uma fila e todas as mensagens contidas nela, recorra ao método QueueClient da classe Delete. O exemplo a seguir mostra como excluir a fila específica usada neste exercício.

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

Limpar os recursos

Remova o grupo de recursos para excluir os ativos e recursos criados neste exercício. Nesse caso, a conta de armazenamento e o próprio grupo de recursos também serão excluídos.

Remove-AzResourceGroup -Name $resourceGroup

Próximas etapas

Neste artigo de instruções, você aprendeu sobre gerenciamento de Armazenamento de Filas básico com o PowerShell, incluindo como:

Cmdlets de armazenamento do Microsoft Azure PowerShell

• Cmdlets do PowerShell do Armazenamento

Gerenciador do Armazenamento do Microsoft Azure

• O Gerenciador de Armazenamento do Microsoft Azure é um aplicativo autônomo e gratuito da Microsoft que possibilita o trabalho visual com os dados do Armazenamento do Azure no Windows, MacOS e Linux.