Suporte do Spring Cloud Azure para o Spring Messaging do Hubs de Eventos do Azure

Este artigo descreve como você pode usar o Spring Cloud Azure e os Hubs de Eventos do Azure do Spring Messaging. O Spring Framework fornece amplo suporte para integração com sistemas de mensagens.

Hub de Eventos do Azure Spring Messaging

Conceitos principais

Os Hubs de Eventos do Azure são um serviço nativo de streaming de dados na nuvem que pode transmitir milhões de eventos por segundo, com baixa latência, de qualquer fonte para qualquer destino. O projeto Spring Messaging para Hubs de Eventos do Azure aplica conceitos básicos do Spring ao desenvolvimento de soluções de mensagens baseadas em hubs de eventos. Ele fornece um modelo como uma abstração de alto nível para enviar mensagens. Ele também dá suporte a POJOs (objetos Java anteriores simples) orientados por mensagens com anotações @EventHubsListener e um contêiner de ouvintes. Essas bibliotecas promovem o uso da injeção de dependência e da configuração declarativa. Em todos esses casos, você pode ver semelhanças com o suporte do JMS no suporte do Spring Framework e do RabbitMQ no Spring AMQP.

Configuração de dependência

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

Configuração

A biblioteca fornece as seguintes opções de configuração para EventHubsTemplate e @EventHubsListener:

Propriedade	Tipo	Descrição
spring.cloud.azure.message-converter.isolated-object-mapper	booleano	Se um bean ObjectMapper isolado é usado no conversor de mensagens do Event Hubs. Habilitado por padrão.
spring.cloud.azure.eventhubs.enabled	booleano	Se um Hub de Eventos do Azure está habilitado.
spring.cloud.azure.eventhubs.connection-string	fio	Valor da cadeia de caracteres de conexão do namespace do Event Hubs.
spring.cloud.azure.eventhubs.namespace	fio	Valor do Namespace dos Hubs de Eventos, que é o prefixo do FQDN. Um FQDN deve ser composto por NamespaceName.DomainName
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name	fio	Nome da conta de armazenamento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key	fio	Chave de acesso da conta de armazenamento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name	fio	Nome do contêiner de armazenamento.

Uso Básico

Conversor de mensagens dos Hubs de Eventos Personalizados

Há duas maneiras de configurar o conversor de mensagens dos Hubs de Eventos:

• Configure a seguinte propriedade para que o conversor de mensagens padrão dos Hubs de Eventos use um ObjectMapper bean, que pode ser seu bean personalizado ObjectMapper ou um gerenciado pelo Spring Boot:

  spring:
    cloud:
      azure:
        message-converter:
          isolated-object-mapper: false
  

• Defina o bean do conversor de mensagens dos Hubs de Eventos diretamente:

  @Bean
  AzureMessageConverter<EventData, EventData> eventHubsMessageConverter() {
      JsonMapper jsonMapper = JsonMapper.builder().addModule(new JavaTimeModule()).build();
      return new EventHubsMessageConverter(jsonMapper);
  }
  

Enviar mensagens aos Hubs de Eventos do Azure

Use as seguintes etapas para enviar mensagens:

1. Preencha as opções de configuração de credencial usando uma das seguintes abordagens:

   • Para credenciais como DefaultAzureCredential, configure as seguintes propriedades em seu arquivo de application.yml:

     spring:
       cloud:
         azure:
           eventhubs:
             namespace: ${AZURE_EVENT_HUBS_NAMESPACE}
             processor:
               checkpoint-store:
                 container-name: ${CHECKPOINT-CONTAINER}
                 account-name: ${CHECKPOINT-STORAGE-ACCOUNT}
     

   • Para credenciais como cadeia de conexão, configure as seguintes propriedades no arquivo application.yml:

     spring:
       cloud:
         azure:
           eventhubs:
             connection-string: ${AZURE_EVENT_HUBS_CONNECTION_STRING}
             processor:
               checkpoint-store:
                 container-name: ${CHECKPOINT-CONTAINER}
                 account-name: ${CHECKPOINT-STORAGE-ACCOUNT}
                 account-key: ${CHECKPOINT-ACCESS-KEY}
     

   • Para credenciais como identidades gerenciadas, configure as seguintes propriedades em seu arquivo application.yml:

     spring:
       cloud:
         azure:
           credential:
             managed-identity-enabled: true
             client-id: ${AZURE_CLIENT_ID}
           eventhubs:
             namespace: ${AZURE_EVENT_HUBS_NAMESPACE}
             processor:
               checkpoint-store:
                 container-name: ${CONTAINER_NAME}
                 account-name: ${ACCOUNT_NAME}
     

   • Para credenciais de service principal, configure as seguintes propriedades no arquivo application.yml:

     spring:
       cloud:
         azure:
           credential:
             client-id: ${AZURE_CLIENT_ID}
             client-secret: ${AZURE_CLIENT_SECRET}
           profile:
             tenant-id: <tenant>
           eventhubs:
             namespace: ${AZURE_EVENT_HUBS_NAMESPACE}
             processor:
               checkpoint-store:
                 container-name: ${CONTAINER_NAME}
                 account-name: ${ACCOUNT_NAME}
     

Observação

Os valores a seguir são permitidos para tenant-id: common, organizations, consumersou a ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Uso do ponto de extremidade incorreto (contas pessoais e de organização) do Error AADSTS50020 – A conta de usuário do provedor de identidade não existe no locatário. Para saber como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

1. EventHubsTemplate é configurado automaticamente, e você pode injetá-lo diretamente em seus próprios beans, conforme mostrado no exemplo a seguir:

   @Component
   public class MyBean {
   
       private final EventHubsTemplate eventHubsTemplate;
   
       public MyBean(EventHubsTemplate eventHubsTemplate) {
           this.eventHubsTemplate = eventHubsTemplate;
       }
   
       public void someMethod() {
           this.eventHubsTemplate.sendAsync('EVENT_HUB_NAME', MessageBuilder.withPayload("Hello world").build()).subscribe();
       }
   
   }
   

Receber mensagens dos Hubs de Eventos do Azure

Use as seguintes etapas para receber mensagens:

1. Preencha as opções de configuração de credencial.

2. Adicione a anotação @EnableAzureMessaging, conforme mostrado no exemplo a seguir. Essa anotação aciona a detecção de métodos anotados com @EventHubsListener e cria, nos bastidores, o contêiner do ouvinte de mensagens.

   @SpringBootApplication
   @EnableAzureMessaging
   public class DemoApplication {
       public static void main(String[] args) {
           SpringApplication.run(DemoApplication.class, args);
       }
   }
   

   Observação

   Para evitar repetição, desde a versão 5.21.0, o Spring Cloud Azure Auto-configure habilita automaticamente a anotação @EnableAzureMessaging.

3. Quando a infraestrutura de Hubs de Eventos estiver disponível, você poderá anotar qualquer bean com @EventHubsListener para criar um ponto de extremidade de ouvinte. O componente a seguir cria um endpoint de escuta no hub de eventos EVENT_HUB_NAME e no grupo de consumidores $Default:

   @Component
   public class MyBean {
   
       @EventHubsListener(destination = "EVENT_HUB_NAME", group = "$Default")
       public void processMessage(String content) {
           // ...
       }
   
   }
   

Exemplos

Para obter mais informações, consulte o azure-spring-boot-samples repositório no GitHub.