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:
- Criar uma fila
- Recuperar uma fila
- Adicionar mensagens
- Recuperar mensagens
- Excluir uma mensagem
- Eliminar uma fila
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.
Nota
Recomendamos que utilize o módulo Azure Az do PowerShell para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.
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 suaDequeueCount
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 suaDequeueCount
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:
- Criar uma fila
- Recuperar uma fila
- Adicionar mensagens
- Ler mensagens
- Excluir mensagens
- Eliminar uma fila
Cmdlets de armazenamento do Microsoft Azure 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.