Use Armazenamento do Azure Queue em aplicações Spring

Este artigo demonstra como usar Armazenamento do Azure Queue em aplicações Java construídas com Spring Framework.

O Armazenamento do Azure Queue implementa filas baseadas na cloud para permitir a comunicação entre componentes de uma aplicação distribuída. Cada fila mantém uma lista de mensagens que podem ser adicionadas por um componente remetente e processadas por um componente recetor. Com uma fila, a sua aplicação pode ser redimensionada imediatamente para atender à procura.

Spring Cloud Azure fornece vários módulos para utilizar frameworks Spring para enviar e receber mensagens de Armazenamento do Azure Queues. Você pode usar esses módulos independentemente ou combiná-los para diferentes casos de uso, conforme descrito na lista a seguir:

Pré-requisitos

Nota

Para dar acesso à sua conta a recursos, na sua conta Armazenamento do Azure recém-criada, atribua o papel Storage Queue Data Contributor à conta Microsoft Entra que está a usar atualmente. Para mais informações, consulte Atribuir Azure funções usando o portal Azure.

Importante

O Spring Boot versão 2.5 ou superior é necessário para concluir as etapas neste tutorial.

Prepare o seu ambiente local

Neste tutorial, as configurações e o código não têm nenhuma operação de autenticação. No entanto, ligar-se a um serviço Azure requer autenticação. Para completar a autenticação, precisa de usar a biblioteca cliente Azure Identity. O Spring Cloud Azure utiliza DefaultAzureCredential, que a biblioteca Azure Identity fornece para te ajudar a obter credenciais sem quaisquer alterações de código.

DefaultAzureCredential Suporta vários métodos de autenticação e determina qual método usar em tempo de execução. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes, como ambientes locais ou de produção, sem implementar código específico do ambiente. Para mais informações, consulte a secção DefaultAzureCredential de Authenticate Azure-hosted Java applications.

Para usar CLI do Azure, IntelliJ ou outros métodos para completar a autenticação em ambientes de desenvolvimento locais, veja Azure autenticação em ambientes de desenvolvimento Java. Para completar a autenticação em ambientes de alojamento Azure, recomendamos o uso de identidade gerida. Para mais informações, consulte O que são identidades geridas para Azure recursos?

Use o Iniciador de Fila de Armazenamento do Spring Cloud Azure

O módulo Spring Cloud Armazenamento do Azure Queue Starter importa a biblioteca cliente Armazenamento do Azure Queue para Java com o framework Spring Boot. Pode usar o Spring Cloud Azure e o SDK do Azure em conjunto, num padrão não mutuamente exclusivo. Assim, pode continuar a usar a API cliente Java da Storage Queue na sua aplicação Spring.

Adicionar dependências

Para instalar o módulo Spring Cloud Armazenamento do Azure Queue Starter, adicione as seguintes dependências ao seu ficheiro pom.xml:

  • A Lista de Materiais Spring Cloud Azure (BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se estiveres a usar o Spring Boot 4.0.x, define a spring-cloud-azure-dependencies versão para 7.4.0.

    Se estiveres a usar o Spring Boot 3.5.x, define a spring-cloud-azure-dependencies versão para 6.5.0.

    Se estiveres a usar o Spring Boot 3.1.x-3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 5.25.0.

    Se você estiver usando o Spring Boot 2.x, certifique-se de definir a versão spring-cloud-azure-dependencies como 4.20.0.

    Esta lista de materiais (BOM) deve ser configurada na seção <dependencyManagement> do seu arquivo pom.xml. Isto garante que todas as dependências do Spring Cloud Azure usam a mesma versão.

    Para mais informações sobre a versão usada nesta BOM, veja Qual Versão do Spring Cloud Azure Devo Usar.

  • O artefacto da fila de armazenamento da Spring Cloud Azure Queue.

    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter-storage-queue</artifactId>
    </dependency>
    

Codifique seu aplicativo para enviar e receber mensagens

Esta secção mostra-lhe como usar os clientes Armazenamento de Filas do Azure no contexto de uma aplicação Spring. Você tem as duas opções a seguir:

  • Utilize a autoconfiguração do Spring Boot e utilize clientes pré-configurados a partir do contexto do Spring (recomendado).
  • Construa o cliente programaticamente.

Com a configuração automática, os beans cliente são conectados automaticamente no contêiner de inversão de controlo (IoC) do Spring. Essa abordagem oferece uma experiência mais flexível e eficiente ao desenvolver com Storage Queue clients. A configuração automática tem as seguintes vantagens:

  • A configuração automática usa a configuração externalizada para que você possa trabalhar com o mesmo código de aplicativo em ambientes diferentes.

  • Você pode delegar à estrutura do Spring Boot o processo de aprender o padrão do construtor e registrar os clientes no contexto do aplicativo. Você se concentra apenas em como usar os clientes com seus próprios requisitos de negócios.

  • Você pode usar o indicador de integridade para inspecionar o status e a integridade do seu aplicativo e componentes internos.

Os exemplos de código nas seções a seguir mostram como usar QueueClient com as duas alternativas descritas.

Gorjeta

Azure Java SDK para a Fila de Armazenamento fornece múltiplos clientes para interagir com a Fila de Armazenamento. O starter também fornece configuração automática para todos os clientes e construtores de clientes das Filas de Armazenamento. Este artigo usa apenas QueueClient como exemplo.

Usar a configuração automática do Spring Boot

Para enviar mensagens e receber mensagens das filas do Armazenamento do Azure, utilize os seguintes passos para configurar a aplicação:

  1. Configure o nome da conta de armazenamento e o nome da fila, conforme mostrado no exemplo a seguir:

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    spring.cloud.azure.storage.queue.queue-name=<your-storage-queue-name>
    
  2. Injete o QueueClient em seu aplicativo Spring e chame as APIs relacionadas para enviar mensagens, conforme mostrado no exemplo a seguir:

    import com.azure.storage.queue.QueueClient;
    import com.azure.storage.queue.models.QueueMessageItem;
    import com.azure.storage.queue.models.SendMessageResult;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class StorageQueueClientApplication implements CommandLineRunner {
    
        private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    
        @Autowired
        private QueueClient queueClient;
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueClientApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
         // Using the QueueClient object, call the create method to create the queue in your storage account.
            queueClient.create();
            SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
            logger.info("Send message id: {}", sendMessageResult.getMessageId());
    
            QueueMessageItem queueMessageItem = queueClient.receiveMessage();
            logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
        }
    
    }
    
  3. Inicie a aplicação. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo a seguir:

    Send message id: ...
    Received message: Hello world
    

Desenvolva o cliente de forma programática

Você pode construir os componentes do cliente sozinho, mas o processo é complicado. Em aplicativos Spring Boot, você precisa gerenciar propriedades, aprender o padrão do construtor e registrar os clientes no contexto do aplicativo Spring. As etapas a seguir mostram como fazer isso.

  1. Crie o cliente programaticamente em seu aplicativo Spring, conforme mostrado no exemplo a seguir. Certifique-se de substituir o marcador de posição <storage-account-name> pelo seu próprio valor.

    import com.azure.identity.DefaultAzureCredentialBuilder;
    import com.azure.storage.queue.QueueClient;
    import com.azure.storage.queue.QueueClientBuilder;
    import com.azure.storage.queue.models.QueueMessageItem;
    import com.azure.storage.queue.models.SendMessageResult;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class StorageQueueClientApplication implements CommandLineRunner {
    
        private final static String queueName = "test-queue";
        private final static String endpoint = "https://<storage-account-name>.queue.core.windows.net/";
        private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    
        QueueClient queueClient = new QueueClientBuilder()
            .endpoint(endpoint)
            .queueName(queueName)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueClientApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
         // Using the QueueClient object, call the create method to create the queue in your storage account.
            queueClient.create();
            SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
            logger.info("Send message id: {}", sendMessageResult.getMessageId());
    
            QueueMessageItem queueMessageItem = queueClient.receiveMessage();
            logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
        }
    
    }
    
  2. Inicie a aplicação. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo a seguir:

    Send message id: ...
    Received message: Hello world
    

A lista a seguir mostra os motivos pelos quais este código não é flexível ou elegante:

  • Os nomes da conta de armazenamento e da fila são codificados.
  • Se você usar @Value para obter configurações do ambiente Spring, não poderá ter dicas do IDE no arquivo application.properties .
  • Se você tiver um cenário de microsserviço, deverá duplicar o código em cada projeto, e é fácil cometer erros e difícil ser consistente.

Felizmente, não é necessário construir os beans do cliente por conta própria com o Spring Cloud Azure. Em vez disso, você pode injetá-los diretamente e usar as propriedades de configuração com as quais já está familiarizado para configurar a fila de armazenamento. Para mais informações, consulte Spring Cloud Azure propriedades de configuração.

O Spring Cloud Azure também fornece as seguintes configurações globais para diferentes cenários. Para mais informações, consulte Spring Cloud Azure global configuration properties.

  • Opções de proxy.
  • Opções de nova tentativa.

Também podes ligar-te a diferentes clouds do Azure. Para mais informações, veja Conectar-se a diferentes nuvens Azure.

Utilize Spring Messaging no Armazenamento do Azure Queue

O módulo Spring Messaging Armazenamento do Azure Queue fornece suporte para o framework Spring Mensaging com Armazenamento de Filas do Azure.

Se estiver a usar a Spring Messaging Armazenamento do Azure Queue, pode usar a funcionalidade StorageQueueTemplate para enviar mensagens para filas de armazenamento de forma assíncrona e síncrona.

As secções seguintes mostram-lhe como usar o Spring Messaging Armazenamento do Azure Queue para enviar e receber mensagens a partir de filas de armazenamento.

Adicionar dependências

Para instalar o módulo Spring Messaging Armazenamento do Azure Queue, adicione as seguintes dependências ao seu ficheiro pom.xml:

  • A Lista de Materiais Spring Cloud Azure (BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se estiveres a usar o Spring Boot 4.0.x, define a spring-cloud-azure-dependencies versão para 7.4.0.

    Se estiveres a usar o Spring Boot 3.5.x, define a spring-cloud-azure-dependencies versão para 6.5.0.

    Se estiveres a usar o Spring Boot 3.1.x-3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 5.25.0.

    Se você estiver usando o Spring Boot 2.x, certifique-se de definir a versão spring-cloud-azure-dependencies como 4.20.0.

    Esta lista de materiais (BOM) deve ser configurada na seção <dependencyManagement> do seu arquivo pom.xml. Isto garante que todas as dependências do Spring Cloud Azure usam a mesma versão.

    Para mais informações sobre a versão usada nesta BOM, veja Qual Versão do Spring Cloud Azure Devo Usar.

  • Os artefatos do Spring Cloud Azure Starter e da Spring Messaging Storage Queue:

    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter</artifactId>
    </dependency>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-messaging-azure-storage-queue</artifactId>
    </dependency>
    

Codifique seu aplicativo para enviar e receber mensagens

Use as seguintes etapas para configurar e codificar seu aplicativo:

  1. Configure o nome da conta Armazenamento do Azure para as suas filas de armazenamento, como mostrado no seguinte exemplo:

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Conecte um remetente e um recetor para enviar e receber mensagens com o Spring, conforme mostrado no exemplo a seguir. Certifique-se de substituir o marcador de posição <storage-queue-name> pelo seu próprio valor.

    import com.azure.spring.messaging.AzureHeaders;
    import com.azure.spring.messaging.checkpoint.Checkpointer;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.messaging.Message;
    import org.springframework.messaging.support.MessageBuilder;
    import java.time.Duration;
    
    @SpringBootApplication
    public class StorageQueueMessagingApplication implements CommandLineRunner {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(StorageQueueMessagingApplication.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
    
        @Autowired
        StorageQueueTemplate storageQueueTemplate;
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueMessagingApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
            storageQueueTemplate
                .sendAsync(STORAGE_QUEUE_NAME, MessageBuilder.withPayload("Hello world").build())
                .subscribe();
            LOGGER.info("Message was sent successfully.");
    
            Message<?> message = storageQueueTemplate.receiveAsync(STORAGE_QUEUE_NAME, Duration.ofSeconds(30)).block();
            LOGGER.info("Received message: {}", new String((byte[]) message.getPayload()));
        }
    
    }
    
  3. Inicie a aplicação. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo a seguir:

    Message was sent successfully.
    ...
    Received message: Hello World
    

Utilizar o Spring Integration para Fila de Armazenamento do Azure

O módulo Spring Integration Armazenamento do Azure Queue fornece suporte para o framework Spring Integration com filas de armazenamento.

Se seu aplicativo Spring usa canais de mensagem do Spring Integration, você pode rotear mensagens entre seus canais de mensagem e fila de armazenamento usando adaptadores de canal. Um adaptador de canal de entrada encaminha mensagens de uma fila de armazenamento para um canal de mensagens. Um adaptador de canal de saída publica mensagens de um canal de mensagens para uma fila de armazenamento.

As secções seguintes mostram-lhe como usar o Spring Integration Armazenamento do Azure Queue para enviar e receber mensagens de e para filas de armazenamento.

Adicionar dependências

Para instalar o módulo Spring Integration Armazenamento do Azure Queue, adicione as seguintes dependências ao seu ficheiro pom.xml:

  • A Lista de Materiais Spring Cloud Azure (BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se estiveres a usar o Spring Boot 4.0.x, define a spring-cloud-azure-dependencies versão para 7.4.0.

    Se estiveres a usar o Spring Boot 3.5.x, define a spring-cloud-azure-dependencies versão para 6.5.0.

    Se estiveres a usar o Spring Boot 3.1.x-3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 5.25.0.

    Se você estiver usando o Spring Boot 2.x, certifique-se de definir a versão spring-cloud-azure-dependencies como 4.20.0.

    Esta lista de materiais (BOM) deve ser configurada na seção <dependencyManagement> do seu arquivo pom.xml. Isto garante que todas as dependências do Spring Cloud Azure usam a mesma versão.

    Para mais informações sobre a versão usada nesta BOM, veja Qual Versão do Spring Cloud Azure Devo Usar.

  • Os artefatos do Spring Integration Armazenamento do Azure Queue:

    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter-integration-storage-queue</artifactId>
    </dependency>
    

Codifique seu aplicativo para enviar e receber mensagens

Use as seguintes etapas para configurar e codificar seu aplicativo:

  1. Configura o nome da conta Armazenamento do Azure para as tuas filas de armazenamento.

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Crie uma nova classe QueueReceiveConfiguration Java como mostrado no exemplo seguinte. Esta classe é usada para definir um recetor de mensagem. Certifique-se de substituir o marcador de posição <storage-queue-name> pelo seu próprio valor.

    import com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource;
    import com.azure.spring.messaging.AzureHeaders;
    import com.azure.spring.messaging.checkpoint.Checkpointer;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.annotation.InboundChannelAdapter;
    import org.springframework.integration.annotation.Poller;
    import org.springframework.integration.annotation.ServiceActivator;
    import org.springframework.messaging.handler.annotation.Header;
    
    @Configuration
    public class QueueReceiveConfiguration {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(QueueReceiveConfiguration.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
        private static final String INPUT_CHANNEL = "input";
    
        @Bean
        @InboundChannelAdapter(channel = INPUT_CHANNEL, poller = @Poller(fixedDelay = "1000"))
        public StorageQueueMessageSource storageQueueMessageSource(StorageQueueTemplate storageQueueTemplate) {
            return new StorageQueueMessageSource(STORAGE_QUEUE_NAME, storageQueueTemplate);
        }
    
        @ServiceActivator(inputChannel = INPUT_CHANNEL)
        public void messageReceiver(byte[] payload, @Header(AzureHeaders.CHECKPOINTER) Checkpointer checkpointer) {
            String message = new String(payload);
            LOGGER.info("Received message: {}", message);
        }
    
    }
    
  3. Crie uma nova classe QueueSendConfiguration Java como mostrado no exemplo seguinte. Essa classe é usada para definir um remetente de mensagem. Certifique-se de substituir o marcador de posição <storage-queue-name> pelo seu próprio valor.

    import com.azure.spring.integration.core.handler.DefaultMessageHandler;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.annotation.MessagingGateway;
    import org.springframework.integration.annotation.ServiceActivator;
    import org.springframework.messaging.MessageHandler;
    import org.springframework.util.concurrent.ListenableFutureCallback;
    
    @Configuration
    public class QueueSendConfiguration {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(QueueSendConfiguration.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
        private static final String OUTPUT_CHANNEL = "output";
    
        @Bean
        @ServiceActivator(inputChannel = OUTPUT_CHANNEL)
        public MessageHandler messageSender(StorageQueueTemplate storageQueueTemplate) {
            DefaultMessageHandler handler = new DefaultMessageHandler(STORAGE_QUEUE_NAME, storageQueueTemplate);
            handler.setSendCallback(new ListenableFutureCallback<Void>() {
                @Override
                public void onSuccess(Void result) {
                    LOGGER.info("Message was sent successfully.");
                }
    
                @Override
                public void onFailure(Throwable ex) {
                    LOGGER.info("There was an error sending the message.");
                }
            });
            return handler;
        }
    
        @MessagingGateway(defaultRequestChannel = OUTPUT_CHANNEL)
        public interface StorageQueueOutboundGateway {
            void send(String text);
        }
    
    }
    
  4. Conecte um remetente e um recetor para enviar e receber mensagens com o Spring.

    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.ConfigurableApplicationContext;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.config.EnableIntegration;
    
    @SpringBootApplication
    @EnableIntegration
    @Configuration(proxyBeanMethods = false)
    public class StorageQueueIntegrationApplication {
    
        public static void main(String[] args) {
            ConfigurableApplicationContext applicationContext = SpringApplication.run(StorageQueueIntegrationApplication.class, args);
            QueueSendConfiguration.StorageQueueOutboundGateway storageQueueOutboundGateway = applicationContext.getBeanQueueSendConfiguration.StorageQueueOutboundGateway.class);
            storageQueueOutboundGateway.send("Hello World");
        }
    
    }
    

    Gorjeta

    Lembre-se de adicionar a anotação @EnableIntegration, que habilita a infraestrutura do Spring Integration.

  5. Inicie a aplicação. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo a seguir:

    Message was sent successfully.
    Received message: Hello World
    

Implementar no Azure Spring Apps

Agora que você tem o aplicativo Spring Boot em execução localmente, é hora de movê-lo para a produção. Azure Spring Apps facilita a implementação de aplicações Spring Boot para Azure sem quaisquer alterações de código. O serviço gerencia a infraestrutura dos aplicativos Spring para que os desenvolvedores possam se concentrar em seu código. O Azure Spring Apps oferece gestão do ciclo de vida através de monitorização e diagnóstico abrangentes, gestão de configuração, descoberta de serviços, integração CI/CD, implementações azul-verde e muito mais. Para implementar a sua aplicação para Azure Spring Apps, consulte Implante a sua primeira aplicação para Azure Spring Apps.

Próximos passos

Consulte também

Para mais informações sobre os Spring Boot Starters disponíveis para Microsoft Azure, veja O que é o Spring Cloud Azure?