Use o Azure Service Bus em aplicações Spring

Este artigo mostra-lhe como usar Azure Service Bus em Java aplicações construídas com Spring Framework.

Azure fornece uma plataforma de mensagens assíncrona chamada Azure Service Bus (Service Bus), baseada no padrão Advanced Message Queueing Protocol 1.0 (AMQP 1.0). Pode usar o Service Bus em várias plataformas Azure suportadas.

O Spring Cloud Azure fornece vários módulos para enviar e receber mensagens para o e do Service Bus, em filas, tópicos e subscrições, utilizando os frameworks Spring.

Você pode usar os seguintes módulos independentemente ou combiná-los para diferentes casos de uso:

• Spring Cloud Azure Service Bus Starter permite-lhe enviar e receber mensagens com a biblioteca cliente SDK Service Bus Java com funcionalidades Spring Boot.

• Spring Cloud Azure Service Bus JMS Starter permite-lhe usar a API JMS para enviar e receber mensagens com filas de Service Bus e tópicos/subscrições.

• Spring Messaging Azure Service Bus permite-lhe interagir com Service Bus através da API Spring Messaging.

• Spring Integration Azure Service Bus permite-lhe ligar o Spring Integration Message Channels com Service Bus.

• Spring Cloud Stream Binder para Service Bus permite-lhe usar Service Bus como middleware de mensagens em aplicações Spring Cloud Stream.

Pré-requisitos

• Uma subscrição do Azure - crie uma gratuitamente.
• Kit de Desenvolvimento Java (JDK) versão 8 ou superior.
• Apache Maven, versão 3.0 ou superior.
• Um Azure Service Bus e fila ou tópico/subscrição. Se não tiver um, crie uma fila ou um tópico do Service Bus. Para mais informações, consulte Use o portal do Azure para criar um espaço de nomes do Service Bus e uma fila ou Use o portal do Azure para criar um tópico do Service Bus e subscrições para o tópico.
• Se você não tiver um aplicativo Spring Boot, crie um projeto Maven com o Spring Initializr. Certifique-se de selecionar Maven Project e, em Dependencies, adicionar a dependência Spring Web e depois selecionar Java versão 8 ou superior.

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 Azure CLI, 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?

Utilize o Spring Cloud Azure Service Bus Starter

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

Adicionar a dependência do Service Bus

Para instalar o módulo Spring Cloud Azure Service Bus 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.1.0</version>
         <type>pom</type>
         <scope>import</scope>
         </dependency>
     </dependencies>
  </dependencyManagement>
  

  Nota

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

  Se estiveres a usar o Spring Boot 3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 6.1.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, consulte Qual Versão do Spring Cloud Azure Devo Usar.

• The Spring Cloud Azure Service Bus artefact:

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

Codifique o aplicativo para enviar e receber mensagens

Este guia ensina-te a usar os clientes Service Bus Java no contexto de uma aplicação Spring. Aqui apresentamos duas alternativas. A forma recomendada é utilizar a autoconfiguração do Spring Boot e empregar clientes disponíveis no contexto do Spring. A alternativa é criar os clientes você mesmo de forma programática.

A primeira maneira, que envolve a injeção automática dos beans do cliente do container Spring IoC, tem as seguintes vantagens quando comparada à segunda maneira. Estes benefícios proporcionam-lhe uma experiência mais flexível e eficiente ao desenvolver com clientes da Service Bus.

• Você pode usar a configuração externalizada para que possa trabalhar com o mesmo código de aplicativo em ambientes diferentes.

• Você pode delegar o processo de aprendizagem do padrão do construtor e registrar esse cliente no contexto do aplicativo para a estrutura do Spring Boot. Essa delegação permite que você se concentre em como usar os clientes com seus próprios requisitos de negócios.

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

O exemplo de código a seguir mostra como usar ServiceBusSenderClient e ServiceBusProcessorClient com essas duas alternativas.

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

Para enviar mensagens e receber mensagens do Service Bus, configure a aplicação utilizando os seguintes passos:

1. Configure o namespace e a fila do seu Service Bus, como mostrado no seguinte exemplo:

   spring.cloud.azure.servicebus.namespace=<your-servicebus-namespace-name>
   spring.cloud.azure.servicebus.entity-name=<your-servicebus-queue-name>
   spring.cloud.azure.servicebus.entity-type=queue
   

   Gorjeta

   Aqui usamos a Service Bus queue como exemplo. Para usar topic/subscription, você precisa adicionar a spring.cloud.azure.servicebus.processor.subscription-name propriedade e alterar o entity-type valor para topic.

2. Crie uma nova classe ServiceBusProcessorClientConfiguration Java como mostrado no exemplo seguinte. Essa classe é usada para registrar a mensagem e o manipulador de erros do ServiceBusProcessorClient.

   @Configuration(proxyBeanMethods = false)
   public class ServiceBusProcessorClientConfiguration {
   
       @Bean
       ServiceBusRecordMessageListener processMessage() {
           return context -> {
               ServiceBusReceivedMessage message = context.getMessage();
               System.out.printf("Processing message. Id: %s, Sequence #: %s. Contents: %s%n", message.getMessageId(),
                       message.getSequenceNumber(), message.getBody());
           };
       }
   
       @Bean
       ServiceBusErrorHandler processError() {
           return context -> {
               System.out.printf("Error when receiving messages from namespace: '%s'. Entity: '%s'%n",
                       context.getFullyQualifiedNamespace(), context.getEntityPath());
           };
       }
   }
   

3. Injete o ServiceBusSenderClient em seu aplicativo Spring e chame as APIs relacionadas para enviar mensagens, conforme mostrado no exemplo a seguir:

   @SpringBootApplication
   public class ServiceBusQueueApplication implements CommandLineRunner {
   
       private final ServiceBusSenderClient senderClient;
   
       public ServiceBusQueueApplication(ServiceBusSenderClient senderClient) {
           this.senderClient = senderClient;
       }
   
       public static void main(String[] args) {
           SpringApplication.run(ServiceBusQueueApplication.class, args);
       }
   
       @Override
       public void run(String... args) throws Exception {
           // send one message to the queue
           senderClient.sendMessage(new ServiceBusMessage("Hello, World!"));
           System.out.printf("Sent a message to the queue");
           senderClient.close();
   
           // wait the processor client to consume messages
           TimeUnit.SECONDS.sleep(10);
       }
   
   }
   

   Nota

   Por padrão, o ciclo de vida do componente bean autowired ServiceBusProcessorClient é gerido pelo contexto do Spring. O processador é iniciado automaticamente quando o Contexto do Aplicativo Spring é iniciado e interrompido quando o Contexto do Aplicativo Spring é interrompido. Para desativar esta funcionalidade, configure spring.cloud.azure.servicebus.processor.auto-startup=false.

4. Inicie a aplicação. São mostrados logs semelhantes ao exemplo a seguir:

   Sent a message to the queue
   Processing message. Id: 6f405435200047069a3caf80893a80bc, Sequence #: 1. Contents: Hello, World!
   

Construir clientes do Service Bus de forma programática

Você pode criar esses beans de cliente sozinho, mas o processo é complicado. Em aplicativos Spring Boot, você precisa gerenciar propriedades, aprender o padrão do construtor e registrar o cliente no contexto do aplicativo Spring. O exemplo de código a seguir mostra como fazer isso:

1. Crie uma nova classe ServiceBusClientConfiguration Java como mostrado no exemplo seguinte. Esta classe é usada para declarar os beans ServiceBusSenderClient e ServiceBusProcessorClient.

   @Configuration(proxyBeanMethods = false)
   public class ServiceBusClientConfiguration {
   
       private static final String SERVICE_BUS_FQDN = "<service-bus-fully-qualified-namespace>";
       private static final String QUEUE_NAME = "<service-bus-queue-name>";
   
       @Bean
       ServiceBusClientBuilder serviceBusClientBuilder() {
           return new ServiceBusClientBuilder()
                      .fullyQualifiedNamespace(SERVICE_BUS_FQDN)
                      .credential(new DefaultAzureCredentialBuilder().build());
       }
   
       @Bean
       ServiceBusSenderClient serviceBusSenderClient(ServiceBusClientBuilder builder) {
           return builder
                  .sender()
                  .queueName(QUEUE_NAME)
                  .buildClient();
       }
   
       @Bean
       ServiceBusProcessorClient serviceBusProcessorClient(ServiceBusClientBuilder builder) {
           return builder.processor()
                         .queueName(QUEUE_NAME)
                         .processMessage(ServiceBusClientConfiguration::processMessage)
                         .processError(ServiceBusClientConfiguration::processError)
                         .buildProcessorClient();
       }
   
       private static void processMessage(ServiceBusReceivedMessageContext context) {
           ServiceBusReceivedMessage message = context.getMessage();
           System.out.printf("Processing message. Id: %s, Sequence #: %s. Contents: %s%n",
               message.getMessageId(), message.getSequenceNumber(), message.getBody());
       }
   
       private static void processError(ServiceBusErrorContext context) {
           System.out.printf("Error when receiving messages from namespace: '%s'. Entity: '%s'%n",
                   context.getFullyQualifiedNamespace(), context.getEntityPath());
       }
   }
   

   Nota

   Certifique-se de substituir o marcador <service-bus-fully-qualified-namespace> pelo nome do anfitrião do Service Bus no portal do Azure. Substitua o marcador <service-bus-queue-name> pelo nome da fila que você configurou no seu espaço de nomes do Service Bus.

2. Injete os beans de cliente na sua aplicação, conforme mostrado no exemplo a seguir:

   @SpringBootApplication
   public class ServiceBusQueueApplication implements CommandLineRunner {
   
       private final ServiceBusSenderClient senderClient;
   
       private final ServiceBusProcessorClient processorClient;
   
       public ServiceBusQueueApplication(ServiceBusSenderClient senderClient, ServiceBusProcessorClient processorClient) {
           this.senderClient = senderClient;
           this.processorClient = processorClient;
       }
   
       public static void main(String[] args) {
           SpringApplication.run(ServiceBusQueueApplication.class, args);
       }
   
       @Override
       public void run(String... args) throws Exception {
           // send one message to the queue
           senderClient.sendMessage(new ServiceBusMessage("Hello, World!"));
           System.out.printf("Sent a message to the queue");
           senderClient.close();
   
           System.out.printf("Starting the processor");
           processorClient.start();
           TimeUnit.SECONDS.sleep(10);
           System.out.printf("Stopping and closing the processor");
           processorClient.close();
       }
   
   }
   

3. Inicie a aplicação. São mostrados logs semelhantes ao exemplo a seguir:

   Sent a message to the queue
   Starting the processor
   ...
   Processing message. Id: 6f405435200047069a3caf80893a80bc, Sequence #: 1. Contents: Hello, World!
   Stopping and closing the processor
   

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

• Os nomes de namespace e fila/tópico/assinatura são codificados de forma rígida.
• 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, construir os beans do cliente por si mesmo não é necessário com o Spring Cloud Azure. Em vez disso, podes injetar diretamente os beans e usar as propriedades de configuração com as quais já estás familiarizado para configurar o Service Bus.

O Spring Cloud Azure também fornece as seguintes configurações globais para diferentes cenários. Para mais informações, consulte a secção configuração global para SDKs de Serviço do Azure na documentação de Spring Cloud Azure.

• Opções de proxy.
• Opções de repetição.
• Opções do cliente de transporte AMQP.

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

Utilize o Starter JMS do Spring Cloud Azure Service Bus

O módulo Spring Cloud Azure Service Bus JMS Starter fornece integração Spring JMS com Service Bus. O vídeo seguinte descreve como integrar aplicações Spring JMS com Azure Service Bus usando JMS 2.0.

Este guia mostra-lhe como usar o Spring Cloud Azure Service Bus Starter para a API JMS para enviar e receber mensagens a partir do Service Bus.

Adicionar a dependência do Service Bus

Para instalar o módulo Spring Cloud Azure Service Bus JMS 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.1.0</version>
         <type>pom</type>
         <scope>import</scope>
         </dependency>
     </dependencies>
  </dependencyManagement>
  

  Nota

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

  Se estiveres a usar o Spring Boot 3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 6.1.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, consulte Qual Versão do Spring Cloud Azure Devo Usar.

• "O artefato JMS do Spring Cloud Azure Service Bus:"

  <dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-servicebus-jms</artifactId>
  </dependency>
  

Codifique o aplicativo para enviar e receber mensagens

1. Configure a connection string e o escalão de preços para o seu Service Bus, como mostrado no exemplo seguinte:

   spring.jms.servicebus.connection-string=<service-bus-namespace-connection-string>
   spring.jms.servicebus.pricing-tier=<service-bus-pricing-tier>
   

2. Crie o recetor da mensagem.

   O Spring fornece meios para publicar mensagens para qualquer POJO (Plain Old Java Object). Primeiro, defina uma classe genérica User que armazene e recupere o nome do usuário, conforme mostrado no exemplo a seguir:

   public class User implements Serializable {
   
       private static final long serialVersionUID = -295422703255886286L;
   
       private String name;
   
       public User() {
       }
   
       public User(String name) {
           setName(name);
       }
   
       public String getName() {
           return name;
       }
   
       public void setName(String name) {
           this.name = name;
       }
   }
   

   Gorjeta

   Serializable é implementado para utilizar o método send no JmsTemplate no Spring Framework. Caso contrário, você deve definir um bean personalizado MessageConverter para serializar o conteúdo para JSON em formato de texto. Para mais informações sobre MessageConverter, consulte o projeto oficial inicial do Spring JMS.

3. A partir daqui, pode criar uma nova classe QueueReceiveService Java como mostrado no exemplo seguinte. Esta classe é usada para definir um recetor de mensagem.

   @Component
   public class QueueReceiveService {
   
       private static final String QUEUE_NAME = "<service-bus-queue-name>";
   
       @JmsListener(destination = QUEUE_NAME, containerFactory = "jmsListenerContainerFactory")
       public void receiveMessage(User user) {
           System.out.printf("Received a message from %s.", user.getName());
       }
   }
   

   Nota

   Certifique-se de substituir o marcador <service-bus-queue-name> pelo nome da sua própria fila configurada no seu espaço de nomes do Service Bus.

   Se você estiver usando um tópico/assinatura, altere o destination parâmetro como o nome do tópico e o containerFactory deve ser topicJmsListenerContainerFactory. Além disso, adicione o subscription parâmetro para descrever o nome da assinatura.

4. Conecte um remetente e um recetor para enviar e receber mensagens com o Spring, conforme mostrado no exemplo a seguir:

   @SpringBootApplication
   @EnableJms
   public class ServiceBusJmsStarterApplication {
   
       private static final String QUEUE_NAME = "<service-bus-queue-name>";
   
       public static void main(String[] args) {
           ConfigurableApplicationContext context = SpringApplication.run(ServiceBusJMSQueueApplication.class, args);
           JmsTemplate jmsTemplate = context.getBean(JmsTemplate.class);
   
           // Send a message with a POJO - the template reuse the message converter
           System.out.println("Sending a user message.");
           jmsTemplate.convertAndSend(QUEUE_NAME, new User("Tom"));
       }
   }
   

   Nota

   Certifique-se de substituir o marcador <service-bus-queue-name> pelo nome da sua própria fila configurada no seu espaço de nomes do Service Bus.

   Gorjeta

   Certifique-se de adicionar a @EnableIntegration anotação, que dispara a descoberta de métodos anotados com @JmsListener, criando o contêiner de ouvinte de mensagens sob as capas.

5. Inicie a aplicação. São mostrados logs semelhantes ao exemplo a seguir:

   Sending a user message.
   Received a message from Tom.
   

Outras informações

Para mais informações, consulte Como usar a API JMS com Service Bus e AMQP 1.0.

Utilize Serviço de Barramento do Azure do Spring Messaging

O módulo Spring Messaging Azure Service Bus fornece suporte para o framework Spring Messaging com Service Bus.

Se estiver a usar o Spring Messaging Azure Service Bus, pode usar as seguintes funcionalidades:

• ServiceBusTemplate: enviar mensagens para filas e tópicos do Service Bus de forma síncrona e assíncrona.
• @ServiceBusListener: marcar um método como alvo de um ouvinte de mensagens Service Bus no destino.

Este guia mostra-lhe como usar o Spring Messaging Azure Service Bus para enviar mensagens e receber mensagens do Service Bus.

Adicionar a dependência do Service Bus

Para instalar o módulo Spring Messaging Azure Service Bus, 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.1.0</version>
         <type>pom</type>
         <scope>import</scope>
         </dependency>
     </dependencies>
  </dependencyManagement>
  

  Nota

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

  Se estiveres a usar o Spring Boot 3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 6.1.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, consulte Qual Versão do Spring Cloud Azure Devo Usar.

• Os artefactos iniciais do Spring Messaging Service Bus e do Spring Cloud Azure:

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

Codifique o aplicativo para enviar e receber mensagens

1. Configure o namespace e o tipo de fila para o seu Service Bus, como mostrado no seguinte exemplo:

   spring.cloud.azure.servicebus.namespace=<service-bus-namespace-name>
   spring.cloud.azure.servicebus.entity-type=queue
   

   Nota

   Se estiver a utilizar um tópico/subscrição, altere o spring.cloud.azure.servicebus.entity-type valor para topic.

2. Crie uma nova classe ConsumerService Java como mostrado no exemplo seguinte. Esta classe é usada para definir um recetor de mensagem.

   @Service
   public class ConsumerService {
   
       private static final String QUEUE_NAME = "<service-bus-queue-name>";
   
       @ServiceBusListener(destination = QUEUE_NAME)
       public void handleMessageFromServiceBus(String message) {
           System.out.printf("Consume message: %s%n", message);
       }
   
   }
   

   Nota

   Se estiveres a usar um tópico/assinatura, altera o parâmetro de anotação de destination como o nome do tópico e adiciona o parâmetro group para descrever o nome da assinatura.

3. Conecte um remetente e um recetor para enviar e receber mensagens com o Spring, conforme mostrado no exemplo a seguir:

   @SpringBootApplication
   @EnableAzureMessaging
   public class Application {
   
       private static final String QUEUE_NAME = "<service-bus-queue-name>";
   
       public static void main(String[] args) {
           ConfigurableApplicationContext applicationContext = SpringApplication.run(Application.class);
           ServiceBusTemplate serviceBusTemplate = applicationContext.getBean(ServiceBusTemplate.class);
           System.out.println("Sending a message to the queue.");
           serviceBusTemplate.sendAsync(QUEUE_NAME, MessageBuilder.withPayload("Hello world").build()).subscribe();
       }
   }
   

   Gorjeta

   Certifique-se de adicionar a @EnableAzureMessaging anotação, que dispara a descoberta de métodos anotados com @ServiceBusListener, criando o contêiner de ouvinte de mensagens sob as capas.

4. Inicie a aplicação. São mostrados logs semelhantes ao exemplo a seguir:

   Sending a message to the queue.
   Consume message: Hello world.
   

Utilizar Spring Integration Azure Service Bus

O módulo Spring Integration Azure Service Bus fornece suporte ao framework Spring Integration com o Service Bus.

Se a sua aplicação Spring usar canais de mensagens Spring Integration, pode encaminhar mensagens entre os seus canais de mensagens e o Service Bus usando adaptadores de canal.

Um adaptador de canal de entrada encaminha as mensagens de uma fila do Service Bus ou de uma subscrição para um canal de mensagens. Um adaptador de canal de saída publica mensagens de um canal de mensagens para uma fila e um tópico do Service Bus.

Este guia mostra-lhe como usar o Spring Integration Azure Service Bus para enviar e receber mensagens do Service Bus.

Adicionar a dependência do Service Bus

Para instalar o módulo Spring Cloud Azure Service Bus Integration 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.1.0</version>
         <type>pom</type>
         <scope>import</scope>
         </dependency>
     </dependencies>
  </dependencyManagement>
  

  Nota

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

  Se estiveres a usar o Spring Boot 3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 6.1.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, consulte Qual Versão do Spring Cloud Azure Devo Usar.

• O artefacto de integração Spring Cloud Azure Service Bus:

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

Codifique o aplicativo para enviar e receber mensagens

1. Configure o namespace do seu Service Bus, como mostrado no seguinte exemplo:

   spring.cloud.azure.servicebus.namespace=<your-servicebus-namespace-name>
   

2. Crie uma nova classe QueueReceiveConfiguration Java como mostrado no exemplo seguinte. Esta classe é usada para definir um recetor de mensagem.

   @Configuration
   public class QueueReceiveConfiguration {
   
       private static final String INPUT_CHANNEL = "queue.input";
       private static final String QUEUE_NAME = "<your-servicebus-queue-name>";
       private static final String SERVICE_BUS_MESSAGE_LISTENER_CONTAINER = "queue-listener-container";
   
       /**
        * This message receiver binding with {@link ServiceBusInboundChannelAdapter}
        * via {@link MessageChannel} has name {@value INPUT_CHANNEL}
        */
       @ServiceActivator(inputChannel = INPUT_CHANNEL)
       public void messageReceiver(byte[] payload) {
           String message = new String(payload);
           System.out.printf("New message received: '%s'%n", message);
       }
   
       @Bean(SERVICE_BUS_MESSAGE_LISTENER_CONTAINER)
       public ServiceBusMessageListenerContainer messageListenerContainer(ServiceBusProcessorFactory processorFactory) {
           ServiceBusContainerProperties containerProperties = new ServiceBusContainerProperties();
           containerProperties.setEntityName(QUEUE_NAME);
           return new ServiceBusMessageListenerContainer(processorFactory, containerProperties);
       }
   
       @Bean
       public ServiceBusInboundChannelAdapter queueMessageChannelAdapter(
           @Qualifier(INPUT_CHANNEL) MessageChannel inputChannel,
           @Qualifier(SERVICE_BUS_MESSAGE_LISTENER_CONTAINER) ServiceBusMessageListenerContainer listenerContainer) {
           ServiceBusInboundChannelAdapter adapter = new ServiceBusInboundChannelAdapter(listenerContainer);
           adapter.setOutputChannel(inputChannel);
           return adapter;
       }
   
       @Bean(name = INPUT_CHANNEL)
       public MessageChannel input() {
           return new DirectChannel();
       }
   }
   

3. Crie uma nova classe QueueSendConfiguration Java como mostrado no exemplo seguinte. Essa classe é usada para definir um remetente de mensagem.

   @Configuration
   public class QueueSendConfiguration {
   
       private static final String OUTPUT_CHANNEL = "queue.output";
       private static final String QUEUE_NAME = "<your-servicebus-queue-name>";
   
       @Bean
       @ServiceActivator(inputChannel = OUTPUT_CHANNEL)
       public MessageHandler queueMessageSender(ServiceBusTemplate serviceBusTemplate) {
           serviceBusTemplate.setDefaultEntityType(ServiceBusEntityType.QUEUE);
           DefaultMessageHandler handler = new DefaultMessageHandler(QUEUE_NAME, serviceBusTemplate);
           handler.setSendCallback(new ListenableFutureCallback<Void>() {
               @Override
               public void onSuccess(Void result) {
                   System.out.println("Message was sent successfully.");
               }
   
               @Override
               public void onFailure(Throwable ex) {
                   System.out.println("There was an error sending the message.");
               }
           });
   
           return handler;
       }
   
       /**
        * Message gateway binding with {@link MessageHandler}
        * via {@link MessageChannel} has name {@value OUTPUT_CHANNEL}
        */
       @MessagingGateway(defaultRequestChannel = OUTPUT_CHANNEL)
       public interface QueueOutboundGateway {
           void send(String text);
       }
   }
   

4. Conecte um remetente e um recetor para enviar e receber mensagens com o Spring, conforme mostrado no exemplo a seguir:

   @SpringBootApplication
   @EnableIntegration
   @Configuration(proxyBeanMethods = false)
   public class ServiceBusIntegrationApplication {
   
       public static void main(String[] args) {
           ConfigurableApplicationContext applicationContext = SpringApplication.run(ServiceBusIntegrationApplication.class, args);
           QueueSendConfiguration.QueueOutboundGateway outboundGateway = applicationContext.getBean(QueueSendConfiguration.QueueOutboundGateway.class);
           System.out.println("Sending a message to the queue");
           outboundGateway.send("Hello World");
       }
   
   }
   

   Gorjeta

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

5. Inicie a aplicação. São mostrados logs semelhantes ao exemplo a seguir:

   Message was sent successfully.
   New message received: 'Hello World'
   

Usar Spring Cloud Stream Service Bus Binder

Para chamar a API Service Bus numa aplicação Spring Cloud Stream, use o módulo Spring Cloud Azure Service Bus Stream Binder.

Este guia mostra-lhe como usar o Spring Cloud Stream Service Bus Binder para enviar e receber mensagens do Service Bus.

Adicionar a dependência do Service Bus

Para instalar o módulo Spring Cloud Azure Service Bus Stream Binder, 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.1.0</version>
         <type>pom</type>
         <scope>import</scope>
         </dependency>
     </dependencies>
  </dependencyManagement>
  

  Nota

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

  Se estiveres a usar o Spring Boot 3.5.x, certifica-te de definir a spring-cloud-azure-dependencies versão para 6.1.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, consulte Qual Versão do Spring Cloud Azure Devo Usar.

• O artefacto de integração Spring Cloud Azure Service Bus:

  <dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-stream-binder-servicebus</artifactId>
  </dependency>
  

Codifique o aplicativo para enviar e receber mensagens

1. Configure o namespace do seu Service Bus, como mostrado no seguinte exemplo:

   spring.cloud.azure.servicebus.namespace=<service-bus-namespace-name>
   

2. Crie o recetor da mensagem.

   Para usar seu aplicativo como um coletor de eventos, configure o fichário de entrada especificando as seguintes informações:

   • Declare um Consumer bean que define lógica de manipulação de mensagens. Por exemplo, o seguinte Consumer bean é chamado consume:

     @Bean
     public Consumer<Message<String>> consume() {
         return message -> {
             System.out.printf("New message received: '%s'.%n", message.getPayload());
         };
     }
     

   • Adicione a configuração para especificar o nome queue para consumo, substituindo o marcador de posição <service-bus-queue-name>, conforme mostrado no exemplo a seguir:

     # name for the `Consumer` bean
     spring.cloud.function.definition=consume
     spring.cloud.stream.bindings.consume-in-0.destination=<service-bus-queue-name>
     

     Nota

     Para consumir a partir de uma subscrição Service Bus, certifique-se de alterar as propriedades de ligação consume-in-0 como mostrado no seguinte exemplo:

     spring.cloud.stream.bindings.consume-in-0.destination=<service-bus-topic-name>
     spring.cloud.stream.bindings.consume-in-0.group=<service-bus-subscription-name>
     

3. Crie o remetente da mensagem.

   Para usar seu aplicativo como uma fonte de eventos, configure o fichário de saída especificando as seguintes informações:

   • Defina um Supplier bean que define de onde as mensagens vêm dentro do seu aplicativo.

     @Bean
     return () -> {
             System.out.println("Sending a message.");
             return MessageBuilder.withPayload("Hello world").build();
         };
     }
     

   • Adicione a configuração para especificar o queue nome de envio substituindo o espaço reservado <your-servicebus-queue-name> no exemplo a seguir.

     # "consume" is added from the previous step
     spring.cloud.function.definition=consume;supply
     spring.cloud.stream.bindings.supply-out-0.destination=<your-servicebus-queue-name>
     spring.cloud.stream.servicebus.bindings.supply-out-0.producer.entity-type=queue
     

     Nota

     Para enviar para um tópico Service Bus, certifique-se de alterar o entity-type para topic.

4. Inicie a aplicação. São-lhe mostrados registos semelhantes ao exemplo abaixo:

   Sending a message.
   New message received: 'Hello world'.
   

Desdobrar para o 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 mais Spring Boot Starters disponíveis para Microsoft Azure, consulte O que é Spring Cloud Azure?