Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Visão geral
Este guia mostrará como codificar cenários comuns usando o serviço de Armazenamento de Filas do Azure. Os exemplos são escritos em Java e usam o SDK de Armazenamento do Azure para Java. Os cenários incluem inserindo, espiando, obtendoe excluindo mensagens de fila. O código para criar e excluir filas também é abordado. Para obter mais informações sobre filas, consulte a seção Próximas etapas.
O que é o armazenamento de filas?
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 por meio de chamadas autenticadas usando HTTP ou HTTPS. Uma única mensagem de fila pode ter até 64 KB de tamanho e uma fila pode conter milhões de mensagens, até o limite total de capacidade de uma conta de armazenamento. O armazenamento de filas geralmente é usado para criar um acúmulo de tarefas para serem processadas de forma assíncrona.
Conceitos de serviço de fila
O serviço Fila do Azure contém os seguintes componentes:
Conta de Armazenamento: Todo o acesso ao Armazenamento do Azure é feito por meio de uma conta de armazenamento. Para saber mais sobre as contas de armazenamento, confira Visão geral da conta de armazenamento.
Fila: uma fila contém um conjunto de mensagens. Todas as mensagens devem estar em uma fila. Observe que o nome da fila deve estar em letras minúsculas. Para saber mais sobre filas de nomenclatura, confira Nomenclatura de filas e metadados.
Mensagem: uma mensagem, em qualquer formato, de até 64 KB. O tempo máximo que uma mensagem pode permanecer na fila é de 7 dias. Para a versão 2017-07-29 ou posterior, a vida útil máxima pode ser qualquer número positivo ou -1, indicando que a mensagem não expira. Se esse parâmetro for omitido, a vida útil padrão será de sete dias.
Formato de URL : Filas de são endereçáveis usando o seguinte formato de URL: http://
<storage account>.queue.core.windows.net/<queue>O seguinte URL aponta para uma fila no diagrama:
http://myaccount.queue.core.windows.net/incoming-orders
Crie uma conta de armazenamento do Azure
A maneira mais fácil de criar sua primeira conta de armazenamento do Azure é usando o portal do Azure . Para saber mais, consulte Criar uma conta de armazenamento.
Você também pode criar uma conta de armazenamento do Azure usando do Azure PowerShell, CLI do Azureou o Provedor de Recursos de Armazenamento do Azure para .NET.
Se você preferir não criar uma conta de armazenamento no Azure no momento, também poderá usar o emulador de armazenamento do Azurite para executar e testar seu código em um ambiente local. Para obter mais informações, consulte Usar o emulador do Azurite para o desenvolvimento de Armazenamento do Azure local.
Criar um aplicativo Java
Primeiro, verifique se o sistema de desenvolvimento atende aos pré-requisitos listados em biblioteca de clientes do Armazenamento de Filas do Azure v12 para Java.
Para criar um aplicativo Java chamado queues-how-to-v12:
Em uma janela do console (como cmd, PowerShell ou Bash), use o Maven para criar um novo aplicativo de console com o nome
queues-how-to-v12. Digite o seguinte comandomvnpara criar um projeto Java "Olá Mundo".mvn archetype:generate \ --define interactiveMode=n \ --define groupId=com.queues.howto \ --define artifactId=queues-howto-v12 \ --define archetypeArtifactId=maven-archetype-quickstart \ --define archetypeVersion=1.4mvn archetype:generate ` --define interactiveMode=n ` --define groupId=com.queues.howto ` --define artifactId=queues-howto-v12 ` --define archetypeArtifactId=maven-archetype-quickstart ` --define archetypeVersion=1.4O resultado da geração do projeto deve ser algo similar a:
[INFO] Scanning for projects... [INFO] [INFO] ------------------< org.apache.maven:standalone-pom >------------------- [INFO] Building Maven Stub Project (No POM) 1 [INFO] --------------------------------[ pom ]--------------------------------- [INFO] [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>> [INFO] [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<< [INFO] [INFO] [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom --- [INFO] Generating project in Batch mode [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.queues.howto [INFO] Parameter: artifactId, Value: queues-howto-v12 [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.queues.howto [INFO] Parameter: packageInPathFormat, Value: com/queues/howto [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.queues.howto [INFO] Parameter: groupId, Value: com.queues.howto [INFO] Parameter: artifactId, Value: queues-howto-v12 [INFO] Project created from Archetype in dir: C:\queues\queues-howto-v12 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 6.775 s [INFO] Finished at: 2020-08-17T15:27:31-07:00 [INFO] ------------------------------------------------------------------------Vá para o diretório
queues-howto-v12recém-criado.cd queues-howto-v12
Instalar o pacote
Abra o arquivo pom.xml no seu editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-queue</artifactId>
<version>12.6.0</version>
</dependency>
Configurar seu aplicativo para acessar o Armazenamento de Filas
Adicione as seguintes instruções de importação à parte superior do arquivo Java em que você deseja usar as APIs de Armazenamento do Azure para acessar filas:
// Include the following imports to use queue APIs
import com.azure.core.util.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
Configurar uma string de conexão do Armazenamento do Azure
Um cliente de Armazenamento do Azure usa uma cadeia de conexão de armazenamento para acessar serviços de gerenciamento de dados. Obtenha o nome e a chave de acesso primária para sua conta de armazenamento listada no portal do Azure. Use-os como os valores AccountName e AccountKey na cadeia de conexão. Este exemplo mostra como você pode declarar um campo estático para armazenar a cadeia de conexão:
// Define the connection-string with your values
final String connectStr =
"DefaultEndpointsProtocol=https;" +
"AccountName=your_storage_account;" +
"AccountKey=your_storage_account_key";
Os exemplos a seguir pressupõem que você tenha um objeto String que contém a cadeia de conexão de armazenamento.
Como criar uma fila
Um objeto QueueClient contém as operações para interagir com uma fila. O código a seguir cria um objeto QueueClient. Use o objeto QueueClient para criar a fila que você deseja usar.
public static String createQueue(String connectStr)
{
try
{
// Create a unique name for the queue
String queueName = "queue-" + java.util.UUID.randomUUID();
System.out.println("Creating queue: " + queueName);
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queue = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// Create the queue
queue.create();
return queue.getQueueName();
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println("Error code: " + e.getErrorCode() + "Message: " + e.getMessage());
return null;
}
}
Como adicionar uma mensagem a uma fila
Para inserir uma mensagem em uma fila existente, chame o método sendMessage. Uma mensagem pode ser uma cadeia de caracteres (no formato UTF-8) ou uma matriz de bytes. Aqui está o código que envia uma mensagem de cadeia de caracteres para a fila.
public static void addQueueMessage
(String connectStr, String queueName, String messageText)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
System.out.println("Adding message to the queue: " + messageText);
// Add a message to the queue
queueClient.sendMessage(messageText);
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como espiar a próxima mensagem
Você pode visualizar a mensagem na frente de uma fila sem removê-la chamando peekMessage.
public static void peekQueueMessage
(String connectStr, String queueName)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// Peek at the first message
PeekedMessageItem peekedMessageItem = queueClient.peekMessage();
System.out.println("Peeked message: " + peekedMessageItem.getMessageText());
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como alterar o conteúdo de uma mensagem na fila
Você pode alterar diretamente o conteúdo de uma mensagem na fila. Se a mensagem representar uma tarefa de trabalho, você poderá usar esse recurso para atualizar o status. O código a seguir atualiza uma mensagem de fila com novo conteúdo e define o tempo limite de visibilidade para estender mais 30 segundos. Estender o tempo limite de visibilidade dá ao cliente mais 30 segundos para continuar trabalhando na mensagem. Você também pode manter uma contagem de repetições. Se a mensagem for repetida mais de n vezes, você a excluirá. Esse cenário protege contra uma mensagem que dispara um erro de aplicação sempre que é processado.
O exemplo de código a seguir pesquisa na fila de mensagens, localiza o primeiro conteúdo da mensagem que corresponde a uma cadeia de caracteres de pesquisa, modifica o conteúdo da mensagem e sai.
public static void updateQueueMessage
(String connectStr, String queueName,
String searchString, String updatedContents)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// The maximum number of messages to retrieve is 32
final int MAX_MESSAGES = 32;
// Iterate through the queue messages
for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES))
{
// Check for a specific string
if (message.getMessageText().equals(searchString))
{
// Update the message to be visible in 30 seconds
queueClient.updateMessage(message.getMessageId(),
message.getPopReceipt(),
updatedContents,
Duration.ofSeconds(30));
System.out.println(
String.format("Found message: \'%s\' and updated it to \'%s\'",
searchString,
updatedContents)
);
break;
}
}
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
O exemplo de código a seguir atualiza apenas a primeira mensagem visível na fila.
public static void updateFirstQueueMessage
(String connectStr, String queueName, String updatedContents)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// Get the first queue message
QueueMessageItem message = queueClient.receiveMessage();
// Check for a specific string
if (null != message)
{
// Update the message to be visible in 30 seconds
UpdateMessageResult result = queueClient.updateMessage(message.getMessageId(),
message.getPopReceipt(),
updatedContents,
Duration.ofSeconds(30));
System.out.println("Updated the first message with the receipt: " +
result.getPopReceipt());
}
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como obter o comprimento da fila
Você pode obter uma estimativa do número de mensagens em uma fila.
O método getProperties retorna vários valores, incluindo o número de mensagens atualmente em uma fila. A contagem é aproximada apenas porque as mensagens podem ser adicionadas ou removidas após sua solicitação. O método getApproximateMessageCount retorna o último valor recuperado pela chamada para getProperties, sem chamar o Armazenamento de Filas.
public static void getQueueLength(String connectStr, String queueName)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();
System.out.println(String.format("Queue length: %d", messageCount));
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como desativar a próxima mensagem
Seu código remove uma mensagem de uma fila em duas etapas. Ao chamar receiveMessage, você receberá a próxima mensagem em uma fila. Uma mensagem retornada de receiveMessage torna-se invisível para qualquer outro código que leia mensagens dessa fila. Por padrão, essa mensagem permanece invisível por 30 segundos. Para concluir a remoção da mensagem da fila, você também deve chamar deleteMessage. Se o código não processar uma mensagem, esse processo de duas etapas garantirá que você possa obter a mesma mensagem e tentar novamente. Seu código chama deleteMessage imediatamente após o processamento da mensagem.
public static void dequeueMessage(String connectStr, String queueName)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// Get the first queue message
QueueMessageItem message = queueClient.receiveMessage();
// Check for a specific string
if (null != message)
{
System.out.println("Dequeing message: " + message.getMessageText());
// Delete the message
queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
}
else
{
System.out.println("No visible messages in queue");
}
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Opções adicionais para desativar mensagens
Há duas maneiras de personalizar a recuperação de mensagens de uma fila. Primeiro, obtenha um lote de mensagens (até 32). Em segundo lugar, defina um tempo limite de invisibilidade mais longo ou menor, permitindo que seu código processe totalmente cada mensagem.
O exemplo de código a seguir usa o método receiveMessages para obter 20 mensagens em uma chamada. Em seguida, ele processa cada mensagem usando um loop de for. Ele também define o tempo limite de invisibilidade como cinco minutos (300 segundos) para cada mensagem. O tempo limite para todas as mensagens começa ao mesmo tempo. Quando se passaram cinco minutos desde que foi feita a chamada para receiveMessages, mensagens não excluídas ficarão visíveis novamente.
public static void dequeueMessages(String connectStr, String queueName)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
// The maximum number of messages to retrieve is 20
final int MAX_MESSAGES = 20;
// Retrieve 20 messages from the queue with a
// visibility timeout of 300 seconds (5 minutes)
for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES,
Duration.ofSeconds(300), Duration.ofSeconds(1), new Context("key1", "value1")))
{
// Do processing for all messages in less than 5 minutes,
// deleting each message after processing.
System.out.println("Dequeing message: " + message.getMessageText());
queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
}
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como listar as filas
Para obter uma lista das filas atuais, chame o método QueueServiceClient.listQueues(), que retornará uma coleção de objetos QueueItem.
public static void listQueues(String connectStr)
{
try
{
// Instantiate a QueueServiceClient which will be
// used to list the queues
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder()
.connectionString(connectStr)
.buildClient();
// Loop through the collection of queues.
for (QueueItem queue : queueServiceClient.listQueues())
{
// Output each queue name.
System.out.println(queue.getName());
}
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Como excluir uma fila
Para excluir uma fila e todas as mensagens contidas nela, chame o método delete no objeto QueueClient.
public static void deleteMessageQueue(String connectStr, String queueName)
{
try
{
// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClientBuilder()
.connectionString(connectStr)
.queueName(queueName)
.buildClient();
System.out.println("Deleting queue: " + queueClient.getQueueName());
// Delete the queue
queueClient.delete();
}
catch (QueueStorageException e)
{
// Output the exception message and stack trace
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Dica
Confira o repositório de exemplos de código do Armazenamento do Azure
Para exemplos de código fácil de usar ponta a ponta do Armazenamento do Azure que você pode baixar e executar, consulte nossa lista de Exemplos de Armazenamento do Azure.
Próximas etapas
Agora que você aprendeu as noções básicas do Armazenamento de Filas, siga estes links para saber mais sobre tarefas de armazenamento mais complexas.
- SDK de Armazenamento do Azure para Java
- referência do SDK de cliente de Armazenamento do Azure
- Serviços de Armazenamento do Azure API REST
- blog da equipe de Armazenamento do Azure
Para obter exemplos de código relacionados usando SDKs preteridos do Java versão 8, consulte Exemplos de código usando o Java versão 8.