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 o Spring Messaging Hubs de Eventos do Azure. O Spring Framework fornece suporte extensivo para integração com sistemas de mensagens.

Hubs de Eventos do Azure Spring Messaging

Conceitos-chave

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 origem para qualquer destino. O projeto Spring Messaging for Hubs de Eventos do Azure aplica os principais conceitos 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 fornece suporte para objetos Java antigos (POJOs) simples orientados por mensagem com @EventHubsListener anotações e um contêiner de ouvinte. Essas bibliotecas promovem o uso de injeção de dependência e configuração declarativa. Em todos esses casos, você pode ver semelhanças com o suporte JMS no Spring Framework e o suporte 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 isolado do ObjectMapper é usado para o conversor de mensagens dos Hubs de Eventos. Ativado por padrão.
spring.cloud.azure.eventhubs.enabled	Booleano	Se um Hubs de Eventos do Azure está habilitado.
spring.cloud.azure.eventhubs.connection-string	Cordão	Valor da cadeia de ligação do Namespace do Event Hubs.
spring.cloud.azure.eventhubs.namespace	Cordão	Valor do espaço de nomes do Event Hubs, que é o prefixo do FQDN. Um FQDN deve ser composto por NamespaceName.DomainName
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name	Cordão	Nome da conta de armazenamento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key	Cordão	Chave de acesso da conta de armazenamento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name	Cordão	Nome do recipiente de armazenamento.

Utilização básica

Conversor de mensagens de 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 gerenciado pelo Spring Boot:

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

• Defina diretamente o bean conversor de mensagens do Event Hubs:

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

Enviar mensagens para Hubs de Eventos do Azure

Use as seguintes etapas para enviar mensagens:

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

   • Para credenciais como DefaultAzureCredential, configure as seguintes propriedades no arquivo 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 principal de serviço, configure as seguintes propriedades no ficheiro 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 seguintes valores são permitidos para tenant-id: common, organizations, consumersou o ID do locatário. Para obter mais informações sobre esses valores, consulte a secção Usou o ponto de extremidade errado (contas pessoais e de organização) na secção Erro AADSTS50020 - A conta de utilizador do provedor de identidade não existe no inquilino. Para obter informações sobre 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 autoconectá-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 credenciais.

2. Adicione a @EnableAzureMessaging anotação, conforme mostrado no exemplo a seguir. Essa anotação aciona a descoberta de métodos anotados com @EventHubsListener, criando o contêiner do ouvinte de mensagens sob as cobertas.

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

   Observação

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

3. Se a infraestrutura do Event Hubs estiver presente, pode anotar qualquer bean com @EventHubsListener para criar um ponto final de escuta. O componente seguinte 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 mais informações, consulte o azure-spring-boot-samples repositório no GitHub.