Guia de início rápido: biblioteca de cliente do Armazenamento de Filas do Azure para Java

Introdução à biblioteca de cliente do Armazenamento de Filas do Azure para Java. O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens para recuperação e processamento posteriores. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (Maven) | Amostras

Utilize a biblioteca cliente do Armazenamento de Filas do Azure para Java para:

• Criar uma fila
• Adicionar mensagens a uma fila
• Espreitar mensagens numa fila
• Atualizar uma mensagem numa fila
• Obter o comprimento da fila
• Receber mensagens de uma fila
• Excluir mensagens de uma fila
• Eliminar uma fila

Pré-requisitos

• Java Development Kit (JDK) versão 8 ou superior
• Apache Maven
• Subscrição do Azure - crie uma gratuitamente
• Conta de Armazenamento do Azure - criar uma conta de armazenamento

Preparação

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Filas do Azure para Java.

Criar o projeto

Crie um aplicativo Java chamado queues-quickstart.

1. Em uma janela de console (como cmd, PowerShell ou Bash), use o Maven para criar um novo aplicativo de console com o nome queues-quickstart. Digite o seguinte mvn comando para criar um "Olá, mundo!" Projeto Java.

   • PowerShell
   • Bash

   mvn archetype:generate `
       --define interactiveMode=n `
       --define groupId=com.queues.quickstart `
       --define artifactId=queues-quickstart `
       --define archetypeArtifactId=maven-archetype-quickstart `
       --define archetypeVersion=1.4
   

2. A saída da geração do projeto deve ser algo como isto:

   [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.quickstart
   [INFO] Parameter: artifactId, Value: queues-quickstart
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.quickstart
   [INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.quickstart
   [INFO] Parameter: groupId, Value: com.queues.quickstart
   [INFO] Parameter: artifactId, Value: queues-quickstart
   [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time:  6.394 s
   [INFO] Finished at: 2019-12-03T09:58:35-08:00
   [INFO] ------------------------------------------------------------------------
   

3. Mude para o diretório recém-criado queues-quickstart.

   cd queues-quickstart
   

Instalar os pacotes

Abra o ficheiro pom.xml no seu editor de texto.

Adicione azure-sdk-bom para depender da versão mais recente da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número da versão. Usar azure-sdk-bom evita que você precise especificar a versão de cada dependência individual. Para saber mais sobre o BOM, consulte o arquivo README do BOM do SDK do Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Em seguida, adicione os seguintes elementos de dependência ao grupo de dependências. A dependência azure-identity é necessária para ligações sem palavra-passe aos serviços do Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Configurar a estrutura do aplicativo

No diretório do projeto:

1. Navegue até o diretório /src/main/java/com/queues/quickstart
2. Abra o arquivo App.java no editor
3. Excluir a System.out.println("Hello, world"); instrução
4. Adicionar import instruções

Aqui está o código:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Autenticar no Azure

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a DefaultAzureCredential classe fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código.

Você também pode autorizar solicitações aos serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local inseguro. Qualquer pessoa que obtenha acesso à senha ou chave secreta é capaz de autenticar. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Modelo de objeto

O Armazenamento de Filas do Azure é um serviço para armazenar um grande número de mensagens. Uma mensagem de fila pode ter até 64 KB de tamanho. Uma fila pode conter milhões de mensagens, até o limite de capacidade total de uma conta de armazenamento. As filas são comumente usadas para criar uma lista de pendências de trabalho para processar de forma assíncrona. O armazenamento em fila oferece três tipos de recursos:

• Conta de armazenamento: todo o acesso ao Armazenamento do Azure é feito por meio de uma conta de armazenamento. Para obter mais informações sobre contas de armazenamento, consulte Visão geral da conta de armazenamento
• Fila: uma fila contém um conjunto de mensagens. Todas as mensagens têm de estar numa fila. Tenha em atenção que o nome da fila tem de estar todo em minúsculas. Para obter informações sobre a nomenclatura de filas, veja Nomenclatura de Filas e Metadados.
• Mensagem: uma mensagem, em qualquer formato, até 64 KB. Uma mensagem pode permanecer na fila por no máximo 7 dias. Para a versão 2017-07-29 ou posterior, o tempo máximo de vida pode ser qualquer número positivo ou -1 indicando que a mensagem não expira. Se esse parâmetro for omitido, o tempo de vida padrão será de sete dias.

O diagrama seguinte mostra a relação entre estes recursos.

Use as seguintes classes Java para interagir com esses recursos:

• QueueClientBuilder: A QueueClientBuilder classe configura e instancia um QueueClient objeto.
• QueueServiceClient: O QueueServiceClient permite que você gerencie todas as filas em sua conta de armazenamento.
• QueueClient: A QueueClient classe permite que você gerencie e manipule uma fila individual e suas mensagens.
• QueueMessageItem: A QueueMessageItem classe representa os objetos individuais retornados ao chamar ReceiveMessages em uma fila.

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes ações com a biblioteca de cliente do Armazenamento de Filas do Azure para Java:

• Autorizar o acesso e criar um objeto cliente
• Criar uma fila
• Adicionar mensagens a uma fila
• Espreitar mensagens numa fila de espera
• Atualizar uma mensagem numa fila
• Obter o comprimento da fila
• Receber e excluir mensagens de uma fila
• Excluir uma fila

az login

az login

Connect-AzAccount

import com.azure.identity.*;

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the environment variable
// is created after the application is launched in a console or with
// Visual Studio, the shell or application needs to be closed and reloaded
// to take the environment variable into account.
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

System.out.println("Creating queue: " + queueName);

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
QueueClient queueClient = new QueueClientBuilder()
        .connectionString(connectStr)
        .queueName(queueName)
        .buildClient();

Criar uma fila

Usando o QueueClient objeto, chame o create método para criar a fila em sua conta de armazenamento.

Adicione este código ao final do main método:

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

Adicionar mensagens a uma fila

O trecho de código a seguir adiciona mensagens à fila chamando o sendMessage método. Ele também salva um SendMessageResult retornado de uma sendMessage chamada. O resultado é usado para atualizar a mensagem posteriormente no programa.

Adicione este código ao final do main método:

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Espreitar mensagens numa fila

Veja as mensagens na fila chamando o método peekMessages. Esse método recupera uma ou mais mensagens da frente da fila, mas não altera a visibilidade da mensagem.

Adicione este código ao final do main método:

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Atualizar uma mensagem numa fila

Atualize o conteúdo de uma mensagem chamando o updateMessage método. Esse método pode alterar o tempo limite de visibilidade e o conteúdo de uma mensagem. O conteúdo da mensagem deve ser uma cadeia de caracteres codificada UTF-8 com até 64 KB de tamanho. Juntamente com o novo conteúdo da mensagem, insira o ID da mensagem e o recibo pop utilizando o SendMessageResult que foi previamente salvo no código. O ID da mensagem e o recibo de confirmação identificam qual mensagem deve ser atualizada.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Obter o comprimento da fila

Você pode obter uma estimativa do número de mensagens em uma fila.

O getProperties método retorna vários valores, incluindo o número de mensagens atualmente em uma fila. A contagem é apenas aproximada porque as mensagens podem ser adicionadas ou removidas após o seu pedido. O getApproximateMessageCount método retorna o último valor recuperado pela chamada para getProperties, sem chamar o Armazenamento de Filas.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

Receber e excluir mensagens de uma fila

Baixe mensagens adicionadas anteriormente chamando o receiveMessages método. O código de exemplo também exclui mensagens da fila depois que elas são recebidas e processadas. Neste caso, o processamento consiste apenas em exibir a mensagem na consola.

O aplicativo pausa a entrada do usuário chamando System.console().readLine(); antes de receber e excluir as mensagens. Verifique no seu portal do Azure se os recursos foram criados corretamente, antes de serem excluídos. Quaisquer mensagens não excluídas explicitamente eventualmente se tornam visíveis na fila novamente para outra chance de processá-las.

Adicione este código ao final do main método:

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Ao chamar o receiveMessages método, você pode, opcionalmente, especificar um valor para maxMessages, que é o número de mensagens a serem recuperadas da fila. O padrão é 1 mensagem e o máximo é 32 mensagens. Você também pode especificar um valor para visibilityTimeout, que oculta as mensagens de outras operações para o período de tempo limite. O padrão é 30 segundos.

Eliminar uma fila

O código a seguir limpa os recursos que o aplicativo criou excluindo a fila usando o Delete método.

Adicione este código ao final do main método:

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

Execute o código

Este aplicativo cria e adiciona três mensagens a uma fila do Azure. O código lista as mensagens na fila, recupera-as e exclui-as antes de finalmente excluir a fila.

Na janela do console, navegue até o diretório do aplicativo e, em seguida, compile e execute o aplicativo.

mvn compile

Em seguida, compile o pacote.

mvn package

Use o seguinte mvn comando para executar o aplicativo.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

A saída do aplicativo é semelhante ao exemplo a seguir:

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Quando o aplicativo pausa antes de receber mensagens, verifique sua conta de armazenamento no portal do Azure. Verifique se as mensagens estão na fila.

Pressione a Enter tecla para receber e excluir as mensagens. Quando solicitado, pressione a Enter tecla novamente para excluir a fila e concluir a demonstração.

Próximos passos

Neste guia de início rápido, você aprendeu como criar uma fila e adicionar mensagens a ela usando código Java. Então você aprendeu a espiar, recuperar e excluir mensagens. Finalmente, você aprendeu como excluir uma fila de mensagens.

Para tutoriais, exemplos, inícios rápidos e outra documentação, visite:

• Para exemplos de código relacionados usando SDKs Java versão 8 preteridos, consulte Exemplos de código usando Java versão 8.
• Para obter mais aplicativos de exemplo do Armazenamento de Filas do Azure, consulte Biblioteca de cliente do Armazenamento de Filas do Azure para Java - exemplos.