Como usar o Armazenamento de Filas do Azure do PowerShell

O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens que podem ser acessadas de qualquer lugar do mundo via HTTP ou HTTPS. Para obter informações detalhadas, consulte Introdução ao Armazenamento de Filas do Azure. Este artigo de instruções aborda operações comuns de armazenamento em fila. Sabe como:

Este guia de instruções requer o módulo do Azure PowerShell (Az) v12.0.0. Execute Get-Module -ListAvailable Az para localizar a versão atualmente instalada. Se precisar de atualizar, veja Install Azure PowerShell module (Instalar o módulo do Azure PowerShell).

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

Iniciar sessão no Azure

Inicie sessão na sua subscrição do Azure com o comando Connect-AzAccount e siga as instruções no ecrã. Se necessário, você pode especificar uma assinatura adicionando os TenantId parâmetros e Subscription e incluindo os respetivos valores.

Connect-AzAccount

Recuperar uma lista de locais

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

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

Criar um grupo de recursos

Um grupo de recursos do Azure é um contentor lógico no qual os recursos do Azure são implementados e geridos. Escolha um nome para seu grupo de recursos e armazene-o resourceGroup na variável 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 ResourceGroupName parâmetro, 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 seus objetos de dados como blobs, arquivos, filas e tabelas.

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

Em seguida, crie uma conta de armazenamento padrão de uso geral com 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 ctx variável. A 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 queueName na variável. Este exemplo usa o nome howtoqueuestorage. Em seguida, crie uma fila usando o cmdlet New-AzStorageQueue e passando as queueName variáveis e ctx para os Name parâmetros e Context conforme mostrado.

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

Para obter informações sobre convenções de nomenclatura para o Armazenamento de Filas do Azure, consulte Nomeando 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 e como especificar uma fila usando Name o Get-AzStorageQueue parâmetro.

# 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 .NET conforme exposto no PowerShell. Para adicionar uma mensagem a uma fila, passe sua mensagem como uma cadeia de caracteres para o QueueClient método da SendMessage classe.

Sua 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 detalhar 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 melhor tentativa, primeira a entrar, primeiro a sair.

Dependendo do seu 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 Receive tira a mensagem da fila e incrementa sua DequeueCount propriedade. A menos que uma mensagem seja excluída, ela é reinserida na fila para ser processada novamente.
• Espiar: Recuperar uma mensagem usando Peek permite que você "visualize" mensagens da fila. Peek não coloca a mensagem na fila nem incrementa sua DequeueCount propriedade.

Receber mensagens

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

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

O exemplo a seguir define a variável invisibleTimeout como 10 segundos e, em seguida, 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 e o ReceiveMessages valor de passagem e 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 sua visibilidade, você pode usar os PeekMessage métodos and PeekMessages . 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 PeekMessage métodos 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 MessageId propriedades 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 ReceiveMessage métodos ou ReceiveMessages . Para concluir a remoção da mensagem da fila, passe os valores obtidos da mensagem para o DeleteMessage método.

Este processo é ilustrado nos exemplos seguintes.

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

Eliminar uma fila

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

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

Clean up resources (Limpar 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 são excluídos.

Remove-AzResourceGroup -Name $resourceGroup

Próximos passos

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

Cmdlets de armazenamento do Microsoft Azure PowerShell

• Cmdlets do Armazenamento do PowerShell

Explorador de Armazenamento do Microsoft Azure

• O Explorador de Armazenamento do Microsoft Azure é uma aplicação autónoma e gratuita da Microsoft, que lhe permite trabalhar visualmente com dados do Armazenamento do Azure no Windows, macOS e Linux.