Usar Hubs de Eventos em aplicativos Spring

Este artigo mostra como usar Hubs de Eventos do Azure em aplicativos Java criados com o Spring Framework.

Hubs de Eventos do Azure é uma plataforma de streaming de Big Data e um serviço de ingestão de eventos. Ele pode receber e processar milhões de eventos por segundo. Os dados enviados para um hub de eventos podem ser transformados e armazenados usando qualquer provedor de análise em tempo real ou adaptadores de armazenamento em lote.

O Spring Cloud Azure fornece vários módulos para enviar mensagens e receber mensagens dos Hubs de Eventos usando estruturas spring.

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

Spring Cloud Hubs de Eventos do Azure Starter permite enviar e receber mensagens com a biblioteca de clientes Java SDK do Event Hubs, utilizando recursos do Spring Boot.
Spring Messaging Hubs de Eventos do Azure permite interagir com os Hubs de Eventos por meio da API Spring Messaging.
Spring Integration Hubs de Eventos do Azure permite conectar o Spring Integration Message Channels com Os Hubs de Eventos.
Spring Cloud Azure Stream Event Hubs Binder permite que você use Hubs de Eventos como um middleware de mensagens nos aplicativos do Spring Cloud Stream.
Spring Kafka com Hubs de Eventos do Azure permite que você use Spring Kafka para enviar mensagens e receber mensagens dos Hubs de Eventos.
Spring Cloud Stream Kafka Binder com Hubs de Eventos do Azure permite enviar e receber mensagens por meio do Spring Cloud Stream Kafka Binder com Hubs de Eventos.

Pré-requisitos

Uma assinatura Azure – criar uma gratuitamente.
Java Development Kit (JDK), versão 8 ou superior.
Apache Maven.
CLI do Azure.

Uma instância de Hubs de Eventos do Azure. Para obter mais informações, consulte Quickstart: Criar um hub de eventos usando Azure portal.
Uma conta Armazenamento do Azure para pontos de verificação dos Hubs de Eventos. Para obter mais informações, consulte Criar uma conta de armazenamento.
Um aplicativo Spring Boot. Caso não tiver um, crie um projeto Maven com o Spring Initializr. Lembre-se de selecionar Maven Project e, em Dependencies, adicione a dependência Spring Web e selecione Java versão 8 ou superior.

Observação

Para conceder acesso à sua conta aos recursos, em Hubs de Eventos do Azure, atribua a função Hubs de Eventos do Azure Data Receiver e Hubs de Eventos do Azure Data Sender à conta Microsoft Entra que você está usando no momento. Em seguida, na conta Armazenamento do Azure, atribua a função Storage Blob Data Contributor à conta Microsoft Entra que você está usando no momento. Para obter mais informações sobre como conceder funções de acesso, consulte Atribuir funções do Azure usando o portal do Azure e Autorizar o acesso aos recursos do Event Hubs usando Microsoft Entra ID.

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 Hubs de Eventos do Azure Starter

O módulo Spring Cloud Hubs de Eventos do Azure Starter importa a biblioteca de clientes Event Hubs 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 do Event Hubs em seu aplicativo Spring.

Adicionar dependências

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

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 Hubs de Eventos do Azure:

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

Codificar o aplicativo para enviar e receber mensagens

Este guia ensina como usar os clientes Java dos Hubs de Eventos no contexto de um aplicativo Spring. Aqui, apresentamos as duas seguintes opções:

Use a autoconfiguração do Spring Boot e use clientes prontos para uso do contexto Spring (recomendado).
Crie o cliente programaticamente.

A maneira de conectar automaticamente beans de cliente do contêiner Spring IoC tem as seguintes vantagens, que podem fornecer uma experiência mais flexível e eficiente ao desenvolver com clientes do Hubs de Eventos:

Ele aplica 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 Builder e registrar esse cliente no contexto da aplicação. Essa delegação permite que você se concentre em como usar os clientes de acordo com suas próprias necessidades empresariais.
Você pode usar o indicador de integridade de maneira fácil para inspecionar o status e a integridade do aplicativo e dos componentes internos.

As seções a seguir fornecem exemplos de código que mostram como usar EventProcessorClient e EventHubProducerClient com as duas alternativas.

Observação

Azure Java SDK para Hubs de Eventos fornece vários clientes para interagir com os Hubs de Eventos. O iniciador também fornece configuração automática para todos os clientes dos Hubs de Eventos, bem como criadores de clientes. Este artigo usa apenas EventProcessorClient e EventHubProducerClient como exemplos.

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

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use as seguintes configurações de propriedade para definir o namespace dos Hubs de Eventos e o nome do hub de eventos:

spring.cloud.azure.eventhubs.namespace=<your event-hubs-namespace>
spring.cloud.azure.eventhubs.event-hub-name=<your-event-hub-name>
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name=<your-storage-account-name>
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name=<your-storage-account-container-name>
spring.cloud.azure.eventhubs.processor.consumer-group=$Default

Crie uma nova classe EventHubProcessorClientConfiguration Java, conforme mostrado no exemplo a seguir. Essa classe é usada para registrar o manipulador de mensagens e erros para EventProcessorClient.

import com.azure.spring.cloud.service.eventhubs.consumer.EventHubsErrorHandler;
import com.azure.spring.cloud.service.eventhubs.consumer.EventHubsRecordMessageListener;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class EventHubProcessorClientConfiguration {

    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubProcessorClientConfiguration.class);

    @Bean
    EventHubsRecordMessageListener processEvent() {
        return eventContext->LOGGER.info("Processing event from partition {} with sequence number {} with body: {}",
            eventContext.getPartitionContext().getPartitionId(), eventContext.getEventData().getSequenceNumber(),
            eventContext.getEventData().getBodyAsString());
    }

    @Bean
    EventHubsErrorHandler processError() {
        return errorContext->LOGGER.info("Error occurred in partition processor for partition {}, {}",
            errorContext.getPartitionContext().getPartitionId(),
            errorContext.getThrowable());
    }

}

Injete o EventProcessorClient e EventHubProducerClient em seu aplicativo Spring e chame as APIs relacionadas para enviar e receber mensagens, conforme mostrado no seguinte exemplo:

import com.azure.messaging.eventhubs.EventData;
import com.azure.messaging.eventhubs.EventHubProducerClient;
import com.azure.messaging.eventhubs.EventProcessorClient;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import java.util.Collections;
import java.util.concurrent.TimeUnit;

@SpringBootApplication
public class EventHubClientApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubClientApplication.class);
    private final EventHubProducerClient eventHubProducerClient;
    private final EventProcessorClient eventProcessorClient;

    public EventHubClientApplication(EventHubProducerClient eventHubProducerClient,
                                     EventProcessorClient eventProcessorClient) {
        this.eventHubProducerClient = eventHubProducerClient;
        this.eventProcessorClient = eventProcessorClient;
    }

    public static void main(String[] args) {
        SpringApplication.run(EventHubClientApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        eventProcessorClient.start();
        // Wait for the processor client to be ready
        TimeUnit.SECONDS.sleep(10);

        eventHubProducerClient.send(Collections.singletonList(new EventData("Hello World")));
        LOGGER.info("Successfully sent a message to Event Hubs.");
        eventHubProducerClient.close();
        LOGGER.info("Skip stopping and closing the processor since the processor may not complete the receiving process yet.");
    }

}

Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:

Successfully sent a message to Event Hubs.
...
Processing event from partition 0 with sequence number 0 with body: Hello World
...
Stopping and closing the processor.

Construa o programa do 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 o cliente no contexto do aplicativo Spring. As etapas a seguir mostram como fazer isso.

Crie uma nova classe EventHubClientConfiguration Java, conforme mostrado no exemplo a seguir. Essa classe é usada para declarar os beans EventProcessorClient e EventHubProducerClient. Certifique-se de substituir os marcadores de posição <your event-hubs-namespace>, <your-event-hub-name>, <your-storage-account-name> e <your-storage-account-container-name> pelos seus valores reais.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.messaging.eventhubs.EventHubClientBuilder;
import com.azure.messaging.eventhubs.EventHubProducerClient;
import com.azure.messaging.eventhubs.EventProcessorClient;
import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
import com.azure.messaging.eventhubs.checkpointstore.blob.BlobCheckpointStore;
import com.azure.messaging.eventhubs.models.ErrorContext;
import com.azure.messaging.eventhubs.models.EventContext;
import com.azure.storage.blob.BlobContainerAsyncClient;
import com.azure.storage.blob.BlobContainerClientBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class EventHubClientConfiguration {

    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubClientConfiguration.class);
    private static final String EVENT_HUB_FULLY_QUALIFIED_NAMESPACE = "<your event-hubs-namespace>.servicebus.windows.net";
    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";
    private static final String CONSUMER_GROUP = "$Default";
    private static final String STORAGE_ACCOUNT_ENDPOINT = "https://<your-storage-account-name>.blob.core.windows.net";
    private static final String STORAGE_CONTAINER_NAME = "<your-storage-account-container-name>";

    @Bean
    EventHubClientBuilder eventHubClientBuilder() {
        return new EventHubClientBuilder().credential(EVENT_HUB_FULLY_QUALIFIED_NAMESPACE, EVENT_HUB_NAME,
            new DefaultAzureCredentialBuilder()
                .build());
    }

    @Bean
    BlobContainerClientBuilder blobContainerClientBuilder() {
        return new BlobContainerClientBuilder().credential(new DefaultAzureCredentialBuilder()
                                                   .build())
                                               .endpoint(STORAGE_ACCOUNT_ENDPOINT)
                                               .containerName(STORAGE_CONTAINER_NAME);
    }

    @Bean
    BlobContainerAsyncClient blobContainerAsyncClient(BlobContainerClientBuilder blobContainerClientBuilder) {
        return blobContainerClientBuilder.buildAsyncClient();
    }

    @Bean
    EventProcessorClientBuilder eventProcessorClientBuilder(BlobContainerAsyncClient blobContainerAsyncClient) {
        return new EventProcessorClientBuilder().credential(EVENT_HUB_FULLY_QUALIFIED_NAMESPACE, EVENT_HUB_NAME,
                                                    new DefaultAzureCredentialBuilder()
                                                        .build())
                                                .consumerGroup(CONSUMER_GROUP)
                                                .checkpointStore(new BlobCheckpointStore(blobContainerAsyncClient))
                                                .processEvent(EventHubClientConfiguration::processEvent)
                                                .processError(EventHubClientConfiguration::processError);
    }

    @Bean
    EventHubProducerClient eventHubProducerClient(EventHubClientBuilder eventHubClientBuilder) {
        return eventHubClientBuilder.buildProducerClient();

    }

    @Bean
    EventProcessorClient eventProcessorClient(EventProcessorClientBuilder eventProcessorClientBuilder) {
        return eventProcessorClientBuilder.buildEventProcessorClient();
    }

    public static void processEvent(EventContext eventContext) {
        LOGGER.info("Processing event from partition {} with sequence number {} with body: {}",
            eventContext.getPartitionContext().getPartitionId(), eventContext.getEventData().getSequenceNumber(),
            eventContext.getEventData().getBodyAsString());
    }

    public static void processError(ErrorContext errorContext) {
        LOGGER.info("Error occurred in partition processor for partition {}, {}",
            errorContext.getPartitionContext().getPartitionId(),
            errorContext.getThrowable());
    }

}

Injete o EventProcessorClient e EventHubProducerClient em seu aplicativo Spring, conforme mostrado no seguinte exemplo:

import com.azure.messaging.eventhubs.EventData;
import com.azure.messaging.eventhubs.EventHubProducerClient;
import com.azure.messaging.eventhubs.EventProcessorClient;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import java.util.Collections;
import java.util.concurrent.TimeUnit;

@SpringBootApplication
public class EventHubClientApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubClientApplication.class);
    private final EventHubProducerClient eventHubProducerClient;
    private final EventProcessorClient eventProcessorClient;

    public EventHubClientApplication(EventHubProducerClient eventHubProducerClient,
                                     EventProcessorClient eventProcessorClient) {
        this.eventHubProducerClient = eventHubProducerClient;
        this.eventProcessorClient = eventProcessorClient;
    }

    public static void main(String[] args) {
        SpringApplication.run(EventHubClientApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        eventProcessorClient.start();
        // Wait for the processor client to be ready
        TimeUnit.SECONDS.sleep(10);

        eventHubProducerClient.send(Collections.singletonList(new EventData("Hello World")));
        LOGGER.info("Successfully sent a message to Event Hubs.");
        eventHubProducerClient.close();
        LOGGER.info("Stopping and closing the processor");
        eventProcessorClient.stop();
    }

}

Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:

Successfully sent a message to Event Hubs.
...
Processing event from partition 0 with sequence number 0 with body: Hello World
...
Stopping and closing the processor.

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

O namespace dos Hubs de Eventos e o nome do hub de eventos 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 de client beans por você mesmo 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 configuration.

O Spring Cloud Azure também fornece as seguintes configurações globais para diferentes cenários. Para obter mais informações, consulte a seção Configuração Global para SDKs de Serviço do Azure da Configuração do Spring Cloud Azure.

Opções de proxy.
Opções de nova tentativa.
Opções do cliente de transporte AMQP.

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

Usar o Spring Messaging com o Hubs de Eventos do Azure

O módulo Spring Messaging Hubs de Eventos do Azure oferece suporte ao framework Spring Messaging com o Event Hubs.

Se você estiver usando o Spring Messaging Hubs de Eventos do Azure, poderá usar os seguintes recursos:

EventHubsTemplate: Envie mensagens para um Hubs de Eventos do Azure de forma assíncrona e síncrona.
@EventHubsListener: Marque um método para ser o alvo de um ouvinte de mensagens do Hubs de Eventos do Azure no destino.

Este guia mostra como usar o Spring Messaging Hubs de Eventos do Azure para enviar mensagens e receber mensagens dos Hubs de Eventos.

Adicionar dependências

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

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 starter do Spring Cloud Azure, Spring Messaging Event Hubs e os artefatos do Hubs de Eventos do Azure Checkpoint Store:

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-messaging-azure-eventhubs</artifactId>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-messaging-eventhubs-checkpointstore-blob</artifactId>
</dependency>

Codificar o aplicativo para enviar e receber mensagens

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use as seguintes configurações de propriedade para definir o namespace dos Hubs de Eventos e o Blob de Armazenamento:

spring.cloud.azure.eventhubs.namespace=<your event-hubs-namespace>
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name=<your-storage-account-name>
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name=<your-storage-account-container-name>

Crie uma nova classe ConsumerService 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 <your-event-hub-name> pelo seu valor real.

import com.azure.spring.messaging.eventhubs.implementation.core.annotation.EventHubsListener;
import org.springframework.stereotype.Service;

@Service
public class ConsumerService {

    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";
    private static final String CONSUMER_GROUP = "$DEFAULT";

    @EventHubsListener(destination = EVENT_HUB_NAME, group = CONSUMER_GROUP)
    public void handleMessageFromEventHub(String message) {
        System.out.printf("New message received: %s%n", message);
    }

}

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 <your-event-hub-name> pelo seu valor real.

import com.azure.spring.messaging.eventhubs.core.EventHubsTemplate;
import com.azure.spring.messaging.implementation.annotation.EnableAzureMessaging;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.messaging.support.MessageBuilder;

@SpringBootApplication
@EnableAzureMessaging
public class EventHubMessagingApplication {

    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";
    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubMessagingApplication.class);

    public static void main(String[] args) {
        ConfigurableApplicationContext applicationContext = SpringApplication.run(EventHubMessagingApplication.class);
        EventHubsTemplate eventHubsTemplate = applicationContext.getBean(EventHubsTemplate.class);
        LOGGER.info("Sending a message to the Event Hubs.");
        eventHubsTemplate.sendAsync(EVENT_HUB_NAME, MessageBuilder.withPayload("Hello world").build()).subscribe();
    }

}

Dica

Lembre-se de adicionar a anotação @EnableAzureMessaging, que aciona a descoberta de métodos anotados com @EventHubsListener, criando o contêiner do ouvinte de mensagens nos bastidores.

Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:

Sending a message to the Event Hubs.
New message received: Hello world

Usar o Spring Integration com Hubs de Eventos do Azure

O módulo Spring Integration Hubs de Eventos do Azure oferece suporte para a estrutura Spring Integration com Hubs de Eventos.

Se o aplicativo Spring usar canais de mensagens de integração do Spring, você poderá rotear mensagens entre seus canais de mensagens e Hubs de Eventos usando adaptadores de canal.

Um adaptador de canal de entrada encaminha mensagens de um hub de eventos para um canal de mensagens. Um adaptador de canal de saída publica mensagens de um canal de mensagens em um hub de eventos.

Este guia mostra como usar o Spring Integration Hubs de Eventos do Azure para enviar mensagens e receber mensagens dos Hubs de Eventos.

Adicionar dependências

Para instalar o módulo Do Spring Cloud Hubs de Eventos do Azure Integration Starter, adicione as seguintes dependências ao arquivo pom.xml:

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 de integração do Spring Cloud Hubs de Eventos do Azure:

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

Codificar o aplicativo para enviar e receber mensagens

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use as seguintes configurações de propriedade para definir o namespace dos Hubs de Eventos e o Blob de Armazenamento:

spring.cloud.azure.eventhubs.namespace=<your event-hubs-namespace>
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name=<your-storage-account-name>
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name=<your-storage-account-container-name>

Crie uma nova classe MessageReceiveConfiguration 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 <your-event-hub-name> pelo seu valor real.

import com.azure.spring.integration.eventhubs.inbound.EventHubsInboundChannelAdapter;
import com.azure.spring.messaging.eventhubs.core.EventHubsProcessorFactory;
import com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointConfig;
import com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointMode;
import com.azure.spring.messaging.eventhubs.core.listener.EventHubsMessageListenerContainer;
import com.azure.spring.messaging.eventhubs.core.properties.EventHubsContainerProperties;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.integration.annotation.ServiceActivator;
import org.springframework.integration.channel.DirectChannel;
import org.springframework.messaging.MessageChannel;

@Configuration
public class MessageReceiveConfiguration {

    private static final String INPUT_CHANNEL = "input";
    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";
    private static final String CONSUMER_GROUP = "$Default";
    private static final Logger LOGGER = LoggerFactory.getLogger(MessageReceiveConfiguration.class);

    @ServiceActivator(inputChannel = INPUT_CHANNEL)
    public void messageReceiver(byte[] payload) {
        String message = new String(payload);
        LOGGER.info("New message received: {}", message);
    }

    @Bean
    public EventHubsMessageListenerContainer messageListenerContainer(EventHubsProcessorFactory processorFactory) {
        EventHubsContainerProperties containerProperties = new EventHubsContainerProperties();
        containerProperties.setEventHubName(EVENT_HUB_NAME);
        containerProperties.setConsumerGroup(CONSUMER_GROUP);
        containerProperties.setCheckpointConfig(new CheckpointConfig(CheckpointMode.MANUAL));
        return new EventHubsMessageListenerContainer(processorFactory, containerProperties);
    }

    @Bean
    public EventHubsInboundChannelAdapter messageChannelAdapter(@Qualifier(INPUT_CHANNEL) MessageChannel inputChannel,
                                                                EventHubsMessageListenerContainer listenerContainer) {
        EventHubsInboundChannelAdapter adapter = new EventHubsInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    }

    @Bean
    public MessageChannel input() {
        return new DirectChannel();
    }

}

Crie uma nova classe MessageSendConfiguration 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 <your-event-hub-name> pelo seu valor real.

import com.azure.spring.integration.core.handler.DefaultMessageHandler;
import com.azure.spring.messaging.eventhubs.core.EventHubsTemplate;
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 MessageSendConfiguration {

    private static final Logger LOGGER = LoggerFactory.getLogger(MessageSendConfiguration.class);
    private static final String OUTPUT_CHANNEL = "output";
    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";

    @Bean
    @ServiceActivator(inputChannel = OUTPUT_CHANNEL)
    public MessageHandler messageSender(EventHubsTemplate eventHubsTemplate) {
        DefaultMessageHandler handler = new DefaultMessageHandler(EVENT_HUB_NAME, eventHubsTemplate);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            }

            @Override
            public void onFailure(Throwable ex) {
                LOGGER.error("There was an error sending the message.", ex);
            }
        });

        return handler;
    }

    @MessagingGateway(defaultRequestChannel = OUTPUT_CHANNEL)
    public interface EventHubOutboundGateway {
        void send(String text);
    }

}

Conecte um remetente e um destinatário para enviar e receber mensagens com o Spring, conforme mostrado no seguinte exemplo:

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

    public static void main(String[] args) {
        ConfigurableApplicationContext applicationContext = SpringApplication.run(EventHubIntegrationApplication.class, args);
        MessageSendConfiguration.EventHubOutboundGateway outboundGateway = applicationContext.getBean(MessageSendConfiguration.EventHubOutboundGateway.class);
        outboundGateway.send("Hello World");
    }
}

Dica

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

Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:
```
Message was sent successfully.
New message received: Hello World
```

Usar o Associador de Hubs de Eventos do Spring Cloud Azure Stream

Para chamar a API de Hubs de Eventos em um aplicativo Spring Cloud Stream, use o módulo Spring Cloud Hubs de Eventos do Azure Stream Binder.

Este guia mostra como usar o Associador de Fluxo dos Hubs de Eventos do Spring Cloud para enviar e receber mensagens dos Hubs de Eventos.

Adicionar dependências

Para instalar o módulo do Spring Cloud Hubs de Eventos do Azure Stream Binder, adicione as seguintes dependências ao arquivo pom.xml:

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 Hubs de Eventos do Azure Stream Binder:

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

Codificar o aplicativo para enviar e receber mensagens

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use as seguintes configurações de propriedade para definir o namespace dos Hubs de Eventos e o Blob de Armazenamento:

spring.cloud.azure.eventhubs.namespace=<your event-hubs-namespace>
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name=<your-storage-account-name>
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name=<your-storage-account-container-name>

Crie o receptor da mensagem.

Para usar seu aplicativo como um coletor de eventos, configure o vinculador de entrada concluindo as seguintes tarefas:

Declare um Consumer bean que define a lógica de manipulação de mensagens. Por exemplo, o bean a seguir Consumer tem o nome de consume.

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

Adicione a seguinte configuração para especificar o Event Hub nome para consumo. Certifique-se de substituir o marcador de posição <your-event-hub-name> pelo seu valor real.

# name for the above `Consumer` bean
spring.cloud.stream.function.definition=consume
spring.cloud.stream.bindings.consume-in-0.destination=<your-event-hub-name>
spring.cloud.stream.bindings.consume-in-0.group=$Default
spring.cloud.stream.eventhubs.bindings.consume-in-0.consumer.checkpoint.mode=MANUAL

Crie o remetente da mensagem.

Para usar seu aplicativo como uma fonte de eventos, configure o vinculador de saída concluindo as seguintes tarefas:
- Defina um bean Supplier que defina de onde as mensagens vêm dentro do seu aplicativo, como mostrado no exemplo seguinte:
```
@Bean
public Supplier<Message<String>> supply() {
    return () -> {
        System.out.println("Sending a message.");
        return MessageBuilder.withPayload("Hello world").build();
    };
}
```
- Adicione a seguinte configuração para especificar o Event Hub nome para envio. Certifique-se de substituir o marcador de posição <your-event-hub-name> pelo seu valor real.
```
# "consume" is added from the above step
spring.cloud.stream.function.definition=consume;supply
spring.cloud.stream.bindings.supply-out-0.destination=<your-event-hub-name>
```
Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:
```
Sending a message.
New message received: Hello world.
```

Usar o Spring Kafka com Hubs de Eventos do Azure

O Hubs de Eventos do Azure fornece um ponto de extremidade do Kafka que seus aplicativos existentes baseados em Kafka podem usar. Essa abordagem fornece uma alternativa à execução de seu próprio cluster Kafka. Os Hubs de Eventos funcionam com vários aplicativos Kafka existentes. Para saber mais, consulte Hubs de Eventos para o Apache Kafka.

Este guia mostra como usar Hubs de Eventos do Azure e Spring Kafka para enviar mensagens e receber mensagens dos Hubs de Eventos.

Adicionar dependências

Para instalar os módulos Spring Cloud Azure Starter e Spring Kafka, adicione as seguintes dependências ao arquivo pom.xml:

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 o artefato Spring Kafka:

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.kafka</groupId>
  <artifactId>spring-kafka</artifactId>
</dependency>

Codificar o aplicativo para enviar e receber mensagens

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use a seguinte configuração de propriedade para configurar o namespace dos Hubs de Eventos:
```
spring.kafka.bootstrap-servers=<your event-hubs-namespace>.servicebus.windows.net:9093
```

Use KafkaTemplate para enviar mensagens e @KafkaListener para receber mensagens, conforme mostrado no exemplo a seguir. Certifique-se de substituir o marcador de posição <your-event-hub-name> pelo seu valor real.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.kafka.core.KafkaTemplate;

@SpringBootApplication
public class EventHubKafkaApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(EventHubKafkaApplication.class);
    private static final String EVENT_HUB_NAME = "<your-event-hub-name>";
    private static final String CONSUMER_GROUP = "$Default";
    private final KafkaTemplate<String, String> kafkaTemplate;

    public EventHubKafkaApplication(KafkaTemplate<String, String> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    public static void main(String[] args) {
        SpringApplication.run(EventHubKafkaApplication.class, args);
    }

    @Override
    public void run(String... args) {
        kafkaTemplate.send(EVENT_HUB_NAME, "Hello World");
        LOGGER.info("Message was sent successfully.");
    }

    @KafkaListener(topics = EVENT_HUB_NAME, groupId = CONSUMER_GROUP)
    public void receive(String message) {
        LOGGER.info("New message received: {}", message);
    }

}

Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:
```
Message was sent successfully.
New message received: Hello world
```

Usar o Spring Cloud Stream Kafka Binder com Hubs de Eventos do Azure

O Spring Cloud Stream é uma estrutura que habilita que os desenvolvedores de aplicativos escrevam microsserviços controlados por mensagens. A ponte entre um sistema de mensagens e o Spring Cloud Stream é por meio da abstração do binder. Existem associadores para vários sistemas de mensagens, mas um dos associadores mais usados é para o Apache Kafka.

Este guia mostra como usar Hubs de Eventos do Azure e Spring Cloud Stream Kafka Binder para enviar mensagens e receber mensagens dos Hubs de Eventos.

Adicionar dependências

Para instalar os módulos Spring Cloud Azure Starter e Spring Cloud Stream Binder para Kafka, adicione as seguintes dependências ao arquivo pom.xml:

O Spring Cloud Azure Lista de Materiais (BOM):
```
<dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.azure.spring</groupId>
       <artifactId>spring-cloud-azure-dependencies</artifactId>
       <version>7.3.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.3.0.

Se você estiver usando o Spring Boot 3.5.x, defina a spring-cloud-azure-dependencies versão como 6.4.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 inicial do Spring Cloud Azure:

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-stream-binder-kafka</artifactId>
</dependency>

Codificar o aplicativo para enviar e receber mensagens

Para enviar e receber mensagens dos Hubs de Eventos, configure o aplicativo usando as seguintes etapas:

Use a seguinte configuração de propriedade para definir o broker Kafka:

spring.cloud.stream.kafka.binder.brokers=<your event-hubs-namespace>.servicebus.windows.net:9093

Crie o receptor da mensagem.

Para usar seu aplicativo como um coletor de eventos, configure o vinculador de entrada concluindo as seguintes tarefas:
- Declare um Consumer bean que define a lógica de manipulação de mensagens. Por exemplo, o bean a seguir Consumer tem o nome de consume.
```
@Bean
public Consumer<Message<String>> consume() {
    return message -> {
        System.out.printf("New message received: %s%n", message.getPayload());
    };
}
```
- Adicione a seguinte configuração para especificar o Event Hub nome para consumo. Certifique-se de substituir o marcador de posição <your-event-hub-name> pelo seu valor real.
```
# name for the above `Consumer` bean
spring.cloud.stream.function.definition=consume
spring.cloud.stream.bindings.consume-in-0.destination=<your-event-hub-name>
spring.cloud.stream.bindings.consume-in-0.group=$Default
```
Crie o remetente da mensagem.

Para usar seu aplicativo como uma fonte de eventos, configure o vinculador de saída concluindo as seguintes tarefas:
- Defina um bean Supplier que defina de onde as mensagens vêm dentro do seu aplicativo, como mostrado no exemplo seguinte:
```
@Bean
public Supplier<Message<String>> supply() {
    return () -> {
        System.out.println("Sending a message.");
        return MessageBuilder.withPayload("Hello world").build();
    };
}
```
- Adicione a seguinte configuração para especificar o Event Hub nome para envio. Certifique-se de substituir o marcador de posição <your-event-hub-name> pelo seu valor real.
```
# "consume" is added from the above step
spring.cloud.stream.function.definition=consume;supply
spring.cloud.stream.bindings.supply-out-0.destination=<your-event-hub-name>
```
Inicie o aplicativo. São exibidos logs semelhantes ao exemplo seguinte:
```
Sending a message.
New message received: 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

Azure para desenvolvedores do Spring Spring Cloud Hubs de Eventos do Azure Samples

Confira também

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

Comentários

Esta página foi útil?

Last updated on 2026-04-20

Usar Hubs de Eventos em aplicativos Spring

Pré-requisitos

Preparar o ambiente local

Usar o Spring Cloud Hubs de Eventos do Azure Starter

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

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

Construa o programa do cliente de forma programática

Usar o Spring Messaging com o Hubs de Eventos do Azure

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

Usar o Spring Integration com Hubs de Eventos do Azure

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

Usar o Associador de Hubs de Eventos do Spring Cloud Azure Stream

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

Usar o Spring Kafka com Hubs de Eventos do Azure

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

Usar o Spring Cloud Stream Kafka Binder com Hubs de Eventos do Azure

Adicionar dependências

Codificar o aplicativo para enviar e receber mensagens

Implantar no Aplicativos Spring do Azure

Próximas etapas

Confira também

Comentários

Recursos adicionais