Soporte de Spring Cloud Azure para Spring Messaging Azure Event Hubs

En este artículo se describe cómo puede usar Spring Cloud Azure y Spring Messaging Azure Event Hubs. Spring Framework proporciona una amplia compatibilidad con la integración con sistemas de mensajería.

Azure Event Hubs con Spring Messaging

Conceptos clave

Azure Event Hubs es un servicio nativo de streaming de datos en la nube que puede transmitir millones de eventos por segundo, con baja latencia, desde cualquier origen a cualquier destino. El proyecto Spring Messaging para Azure Event Hubs aplica conceptos básicos de Spring al desarrollo de soluciones de mensajería basadas en Event Hubs. Proporciona una plantilla de como una abstracción de alto nivel para enviar mensajes. También proporciona soporte para objetos Java simples (POJO) basados en mensajes con anotaciones @EventHubsListener y un contenedor de listeners. Estas bibliotecas promueven el uso de la inserción de dependencias y la configuración declarativa. En todos estos casos, se pueden ver similitudes con el soporte de JMS en el Spring Framework y el soporte de RabbitMQ en Spring AMQP.

Configuración de dependencias

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

Configuración

La biblioteca proporciona las siguientes opciones de configuración para EventHubsTemplate y @EventHubsListener:

Propiedad	Tipo	Descripción
spring.cloud.azure.message-converter.isolated-object-mapper	booleano	Si se usa un bean de ObjectMapper aislado para el convertidor de mensajes de Event Hubs. Habilitado de forma predeterminada.
spring.cloud.azure.eventhubs.enabled	booleano	Si una instancia de Azure Event Hubs está habilitada.
spring.cloud.azure.eventhubs.connection-string	Cuerda	Valor de cadena de conexión del espacio de nombres de Event Hubs.
spring.cloud.azure.eventhubs.namespace	Cuerda	Valor del espacio de nombres de Event Hubs, que es el prefijo del FQDN. Un FQDN debe estar compuesto por NamespaceName.DomainName
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name	Cuerda	Nombre de la cuenta de almacenamiento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key	Cuerda	Clave de acceso de la cuenta de almacenamiento.
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name	Cuerda	Nombre del contenedor de almacenamiento.

Uso básico

Convertidor de mensajes de Event Hubs personalizado

Hay dos maneras de configurar el convertidor de mensajes de Event Hubs:

• Configure la siguiente propiedad para que el convertidor de mensajes predeterminado de Event Hubs use un ObjectMapper bean, que puede ser el bean personalizado ObjectMapper o uno administrado por Spring Boot:

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

• Defina directamente el bean del convertidor de mensajes de Event Hubs:

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

Envío de mensajes a Azure Event Hubs

Siga estos pasos para enviar mensajes:

1. Rellene las opciones de configuración de credenciales mediante uno de los métodos siguientes:

   • Para las credenciales como DefaultAzureCredential, configure las siguientes propiedades en el archivo application.yml:

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

   • Para las credenciales como cadena de conexión, configure las siguientes propiedades en el archivo 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 las credenciales como identidades administradas, configure las siguientes propiedades en el archivo 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 las credenciales como principal de servicio, configure las siguientes propiedades en su archivo 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}
     

Nota:

Se permiten los siguientes valores para tenant-id: common, organizations, consumerso el identificador de inquilino. Para obtener más información sobre estos valores, consulte la sección Uso del punto de conexión incorrecto (cuentas personales y de organización) de Error AADSTS50020: la cuenta de usuario del proveedor de identidades no existe en el inquilino. Para obtener información sobre cómo convertir su aplicación de un solo inquilino a multiinquilino, consulte Convertir aplicación de un solo inquilino a multiinquilino en Microsoft Entra ID.

1. EventHubsTemplate está autoconfigurado y puede conectarlo directamente a sus propios beans, tal como se muestra en el ejemplo siguiente:

   @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();
       }
   
   }
   

Recepción de mensajes de Azure Event Hubs

Siga estos pasos para recibir mensajes:

1. Rellene las opciones de configuración de credenciales.

2. Agregue la anotación @EnableAzureMessaging, como se muestra en el ejemplo siguiente. Esta anotación desencadena la detección de métodos anotados con @EventHubsListener, creando el contenedor del agente de escucha de mensajes en segundo plano.

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

   Nota:

   Para evitar repeticiones, desde la versión 5.21.0, Spring Cloud Azure Auto-configure habilita automáticamente la anotación @EnableAzureMessaging.

3. Si la infraestructura de Event Hubs está disponible, puede tomar nota de cualquier bean con @EventHubsListener para crear un punto de conexión de agente de escucha. El componente siguiente crea un extremo de escucha en el centro de eventos EVENT_HUB_NAME y en el grupo de consumidores $Default:

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

Muestras

Para obtener más información, consulte el azure-spring-boot-samples repositorio en GitHub.