Usar Fila de Armazenamento do Azure em aplicações Spring

Este artigo demonstra como usar Armazenamento do Azure Queue em aplicativos Java criados com Spring Framework.

Armazenamento do Azure Fila implementa filas baseadas em nuvem para habilitar a comunicação entre componentes de um aplicativo distribuído. Cada fila mantém uma lista de mensagens que podem ser adicionadas por um componente emissor e processadas por um componente receptor. Com uma fila, o aplicativo pode ser dimensionado imediatamente para atender à demanda.

O Spring Cloud Azure fornece vários módulos para usar frameworks Spring para enviar mensagens e receber mensagens de filas do Armazenamento do Azure. Você pode usar esses módulos de forma independente ou combiná-los para diferentes casos de uso, conforme descrito na seguinte lista:

Pré-requisitos

Observação

Para conceder acesso à sua conta aos recursos, em sua conta de Armazenamento do Azure recém-criada, atribua a função Storage Queue Data Contributor à conta Microsoft Entra que você está usando no momento. Para obter mais informações, consulte Atribuir funções do Azure usando o portal do Azure.

Importante

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

Preparar o ambiente local

Nesse tutorial, as configurações e o código não têm nenhuma operação de autenticação. No entanto, conectar-se a um serviço Azure requer autenticação. Para concluir a autenticação, você precisa usar a biblioteca de clientes do Azure Identity. O Spring Cloud Azure usa DefaultAzureCredential, que a biblioteca de identidades do Azure fornece para ajudá-lo a obter credenciais sem alterações de código.

DefaultAzureCredential dá suporte a vários métodos de autenticação e determina qual método usar no runtime. Essa abordagem habilita seu aplicativo a usar diferentes métodos de autenticação em diferentes ambientes, como ambientes locais ou de produção, sem implementar código específico do ambiente. Para obter mais informações, consulte a seção DefaultAzureCredential de Autenticar aplicativos Java hospedados no Azure.

Para usar CLI do Azure, IntelliJ ou outros métodos para concluir a autenticação em ambientes de desenvolvimento local, consulte Azure autenticação em ambientes de desenvolvimento Java. Para concluir a autenticação em ambientes de hospedagem Azure, é recomendável usar a identidade gerenciada. Para obter mais informações, consulte O que são identidades gerenciadas para recursos Azure?

Usar o Spring Cloud Armazenamento do Azure Queue Starter

O módulo Spring Cloud Armazenamento do Azure Queue Starter importa a biblioteca de cliente do Armazenamento do Azure Queue para Java com o framework Spring Boot. Você pode usar o Spring Cloud Azure e o SDK do Azure juntos, em um padrão não mutuamente exclusivo. Assim, você pode continuar usando a API do cliente Java para fila de armazenamento em seu aplicativo Spring.

Adicionar dependências

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

  • O Spring Cloud Azure Bill of Materials (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>
    

    Observação

    Se você estiver usando o Spring Boot 4.0.x, defina a spring-cloud-azure-dependencies versão como 7.4.0.

    Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.5.0.

    Se você estiver usando o Spring Boot 3.1.x-3.5.x, defina a spring-cloud-azure-dependencies versão como 5.25.0.

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

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

    Para obter mais informações sobre a versão usada para este BOM, consulte Which Version of Spring Cloud Azure Should I Use.

  • O artefato do Spring Cloud Armazenamento de Filas do Azure Queue:

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

Codificar seu aplicativo para enviar e receber mensagens

Esta seção mostra como usar os clientes Armazenamento de Filas do Azure no contexto de um aplicativo Spring. Você tem as seguintes duas opções:

  • Use a configuração automática do Spring Boot e use clientes prontos para uso do contexto do Spring (recomendado).
  • Crie o cliente programaticamente.

Com a configuração automática, você conecta automaticamente os beans do cliente do contêiner de inversão de controle (IoC) do Spring. Essa abordagem fornece uma experiência mais flexível e eficiente ao trabalhar com clientes da Fila de Armazenamento (Storage Queue). 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 ao framework Spring Boot o processo de aprendizado do padrão de construção 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 aplicativo e dos componentes internos.

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

Dica

Azure Java SDK para Fila de Armazenamento fornece vários clientes para interagir com a Fila de Armazenamento. O iniciador também fornece configuração automática para todos os clientes da Fila de Armazenamento e criadores de clientes. Este artigo usa somente QueueClient como exemplo.

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

Para enviar e receber mensagens de filas do Armazenamento do Azure, use as seguintes etapas para configurar o aplicativo:

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

    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 seguinte exemplo:

    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 o aplicativo. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo seguinte:

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

Construa o cliente de forma programática

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

  1. Crie o cliente programaticamente em sua aplicação Spring, conforme mostrado no exemplo a seguir. Certifique-se de substituir o marcador de posição <storage-account-name> por 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 o aplicativo. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo seguinte:

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

A seguinte lista mostra alguns dos motivos pelos quais esse código não é flexível ou gracioso:

  • Os nomes da conta de armazenamento e da fila são codificados.
  • Se você usa @Value para obter configurações do ambiente Spring, não pode ter dicas de IDE em seu 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, a criação dos client beans por conta própria não é necessária 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 obter 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 obter mais informações, consulte Spring Cloud Azure propriedades de configuração global.

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

Você também pode se conectar a diferentes nuvens de Azure. Para obter mais informações, consulte Conectar-se a diferentes nuvens Azure.

Usar o Spring Messaging Fila de Armazenamento do Azure

O módulo Spring Messaging Armazenamento do Azure Queue oferece suporte para a estrutura spring Messaging com Armazenamento de Filas do Azure.

Se você estiver usando o Spring Messaging Armazenamento do Azure Queue, poderá usar o recurso StorageQueueTemplate para enviar mensagens para filas de armazenamento de forma assíncrona e síncrona.

As seções a seguir mostram como usar o Spring Messaging Armazenamento do Azure Queue para enviar mensagens e receber mensagens de filas de armazenamento.

Adicionar dependências

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

  • O Spring Cloud Azure Bill of Materials (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>
    

    Observação

    Se você estiver usando o Spring Boot 4.0.x, defina a spring-cloud-azure-dependencies versão como 7.4.0.

    Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.5.0.

    Se você estiver usando o Spring Boot 3.1.x-3.5.x, defina a spring-cloud-azure-dependencies versão como 5.25.0.

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

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

    Para obter mais informações sobre a versão usada para este BOM, consulte Which Version of Spring Cloud Azure Should I Use.

  • O iniciador do Spring Cloud Azure e os artefatos da Fila de Armazenamento de Mensagens do Spring:

    <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>
    

Codificar seu aplicativo para enviar e receber mensagens

Use as etapas seguintes para configurar e codificar seu aplicativo:

  1. Configure o nome da conta Armazenamento do Azure para suas filas de armazenamento, conforme mostrado no exemplo a seguir:

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Conecte um remetente e um destinatário 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> por 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 o aplicativo. Após a inicialização, o aplicativo produz logs semelhantes ao exemplo seguinte:

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

Utilizar o Spring Integration para Armazenamento do Azure Queue

O módulo Spring Integration Armazenamento do Azure Queue oferece suporte para a estrutura Spring Integration com filas de armazenamento.

Se o seu aplicativo Spring usa canais de mensagem da Integração Spring, você pode rotear mensagens entre os canais de mensagem e a 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 em uma fila de armazenamento.

As seções a seguir mostram 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 arquivo pom.xml:

  • O Spring Cloud Azure Bill of Materials (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>
    

    Observação

    Se você estiver usando o Spring Boot 4.0.x, defina a spring-cloud-azure-dependencies versão como 7.4.0.

    Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.5.0.

    Se você estiver usando o Spring Boot 3.1.x-3.5.x, defina a spring-cloud-azure-dependencies versão como 5.25.0.

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

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

    Para obter mais informações sobre a versão usada para este BOM, consulte Which Version of Spring Cloud Azure Should I Use.

  • Os componentes do Spring Integration Armazenamento do Azure Queue:

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

Codificar seu aplicativo para enviar e receber mensagens

Use as etapas seguintes para configurar e codificar seu aplicativo:

  1. Configure o nome da conta Armazenamento do Azure para suas filas de armazenamento.

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Crie uma nova classe QueueReceiveConfiguration Java, conforme mostrado no exemplo a seguir. Essa classe é usada para definir um receptor de mensagem. Certifique-se de substituir o marcador de posição <storage-queue-name> por 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, conforme mostrado no exemplo a seguir. Essa classe é usada para definir um remetente de mensagem. Certifique-se de substituir o marcador de posição <storage-queue-name> por 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 destinatário 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");
        }
    
    }
    

    Dica

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

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

    Message was sent successfully.
    Received message: Hello World
    

Implantar no Aplicativos Spring do Azure

Agora que você tem o aplicativo Spring Boot em execução localmente, é hora de movê-lo para produção. Aplicativos Spring do Azure facilita a implantação de aplicativos Spring Boot para Azure sem alterações de código. O serviço gerencia a infraestrutura dos aplicativos do Spring para que os desenvolvedores possam se concentrar no código. Aplicativos Spring do Azure fornece gerenciamento de ciclo de vida usando monitoramento e diagnóstico abrangentes, gerenciamento de configuração, descoberta de serviço, integração de CI/CD, implantações azul-verde e muito mais. Para implantar seu aplicativo em Aplicativos Spring do Azure, consulte Deploy seu primeiro aplicativo para Aplicativos Spring do Azure.

Próximas etapas

Confira também

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