Supporto di Spring Cloud Azure per Hub eventi di Azure in Spring Messaging

Questo articolo descrive come usare Spring Cloud Azure e Spring Messaging Hub eventi di Azure. Spring Framework offre un ampio supporto per l'integrazione con i sistemi di messaggistica.

Spring Messaging - Hub degli Eventi di Azure

Concetti chiave

Hub eventi di Azure è un servizio di streaming di dati nativo nel cloud che può trasmettere milioni di eventi al secondo, con bassa latenza, da qualsiasi origine a qualsiasi destinazione. Il progetto Spring Messaging per Hub eventi di Azure applica i concetti di base di Spring allo sviluppo di soluzioni di messaggistica basate su Hub eventi. Fornisce un modello come astrazione di alto livello per l'invio di messaggi. Fornisce inoltre supporto per semplici oggetti Java (POJO) guidati dai messaggi con annotazioni @EventHubsListener e un contenitore listener. Queste librerie promuovono l'uso dell'inserimento delle dipendenze e della configurazione dichiarativa. In tutti questi casi è possibile osservare analogie con il supporto JMS nel supporto Spring Framework e RabbitMQ in Spring AMQP.

Configurazione delle dipendenze

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

Configurazione

La libreria offre le opzioni di configurazione seguenti per EventHubsTemplate e @EventHubsListener:

Proprietà	TIPO	Descrizione
spring.cloud.azure.message-converter.isolated-object-mapper	booleano	Se viene utilizzato un bean ObjectMapper isolato per il convertitore di messaggi di Event Hubs. Abilitato per impostazione predefinita.
spring.cloud.azure.eventhubs.enabled	booleano	Indica se hub eventi di Azure è abilitato.
spring.cloud.azure.eventhubs.connection-string	Stringa	Valore della stringa di connessione dello spazio dei nomi di Event Hubs.
spring.cloud.azure.eventhubs.namespace	Stringa	Valore dello spazio dei nomi di Hub di eventi, ovvero il prefisso del nome di dominio completo. Un FQDN deve essere composto da NamespaceName.DomainName
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name	Stringa	Nome dell'account di archiviazione.
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key	Stringa	Chiave di accesso dell’account di archiviazione.
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name	Stringa	Nome del contenitore di archiviazione.

Utilizzo di base

Convertitore di messaggi personalizzato di Hub eventi

Esistono due modi per configurare il convertitore di messaggi di Hub eventi:

• Configurare la proprietà seguente in modo che il convertitore di messaggi di Hub eventi predefinito usi un ObjectMapper bean, che può essere il bean personalizzato ObjectMapper o uno gestito da Spring Boot:

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

• Definire direttamente il bean del convertitore di messaggi di Event Hubs:

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

Inviare messaggi a Hub eventi di Azure

Per inviare messaggi, seguire questa procedura:

1. Compilare le opzioni di configurazione delle credenziali usando uno degli approcci seguenti:

   • Per le credenziali come DefaultAzureCredential, configurare le proprietà seguenti nel file application.yml:

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

   • Per le credenziali come stringa di connessione, configurare le proprietà seguenti nel file 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}
     

   • Per le credenziali come identità gestite, configurare le proprietà seguenti nel file 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}
     

   • Per le credenziali del service principal, configura le proprietà seguenti nel file 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}
     

Annotazioni

Per tenant-idsono consentiti i valori seguenti: common, organizations, consumerso l'ID tenant. Per ulteriori informazioni su questi valori, consultare la sezione Utilizzato l'endpoint sbagliato (account personali e organizzativi) di Errore AADSTS50020 - L'account utente del provider di identità non esiste nel tenant. Per informazioni sulla conversione della tua app a tenant singolo in multi-tenant, vedere Convertire app a tenant singolo in multi-tenant in Microsoft Entra ID.

1. EventHubsTemplate viene configurato automaticamente ed è possibile iniettarlo direttamente nei propri bean, come mostrato nell'esempio seguente:

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

Ricevere messaggi da Hub eventi di Azure

Per ricevere messaggi, seguire questa procedura:

1. Immettere le opzioni di configurazione delle credenziali.

2. Aggiungere l'annotazione @EnableAzureMessaging, come illustrato nell'esempio seguente. Questa annotazione attiva il rilevamento dei metodi annotati con @EventHubsListener, creando dietro le quinte il contenitore del listener di messaggi.

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

   Annotazioni

   Per evitare ripetizioni, a partire dalla versione 5.21.0, Spring Cloud Azure Auto-configure abilita automaticamente l'annotazione @EnableAzureMessaging.

3. Quando l'infrastruttura di Hub eventi è presente, è possibile annotare qualsiasi bean con @EventHubsListener per creare un endpoint del listener. Il componente seguente crea un endpoint di listener sull'hub eventi EVENT_HUB_NAME e nel gruppo di consumer $Default:

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

Esempi

Per altre informazioni, vedere il azure-spring-boot-samples repository in GitHub.