Condividi tramite


Usare Java per inviare o ricevere eventi da Hub eventi di Azure

Questa guida di avvio rapido illustra come inviare e ricevere eventi da un hub eventi con il pacchetto Java azure-messaging-eventhubs.

Suggerimento

Se si usa Hub eventi di Azure risorse in un'applicazione Spring, è consigliabile prendere in considerazione Spring Cloud Azure come alternativa. Spring Cloud Azure è un progetto open source che offre un'integrazione spring senza problemi con i servizi di Azure. Per altre informazioni su Spring Cloud Azure e per un esempio relativo all'uso di Hub eventi, vedere Spring Cloud Stream con Hub eventi di Azure.

Prerequisiti

Se non si ha familiarità con Hub eventi di Azure, vedere Panoramica di Hub eventi prima di procedere con questa guida di avvio rapido.

Per completare questa guida introduttiva è necessario soddisfare i prerequisiti seguenti:

  • Sottoscrizione di Microsoft Azure. Per usare i servizi di Azure, tra cui Hub eventi di Azure, è necessaria una sottoscrizione. Se non si ha un account Azure, è possibile iscriversi per ottenere una versione di valutazione gratuita oppure usare i vantaggi della sottoscrizione di MSDN per la creazione di un account.
  • Ambiente di sviluppo in Java. In questa guida di avvio rapido si usa Eclipse. È necessario Java Development Kit (JDK) versione 8 o successiva.
  • Creare uno spazio dei nomi di Hub eventi e un hub eventi. Il primo passaggio consiste nell'usare il portale di Azure per creare uno spazio dei nomi di tipo Hub eventi e ottenere le credenziali di gestione necessarie all'applicazione per comunicare con l'hub eventi. Per creare uno spazio dei nomi e un hub eventi, seguire la procedura descritta in questo articolo. Ottenere quindi il stringa di connessione per lo spazio dei nomi di Hub eventi seguendo le istruzioni riportate nell'articolo: Ottenere stringa di connessione. La stringa di connessione sarà necessaria più avanti in questa guida di avvio rapido.

Inviare gli eventi

Questa sezione illustra come creare un'applicazione Java per inviare eventi a un hub eventi.

Aggiungere il riferimento alla libreria di Hub eventi di Azure

Creare prima di tutto un nuovo progetto Maven per un'applicazione console/shell nell'ambiente di sviluppo Java preferito. Aggiornare il pom.xml file come indicato di seguito. La libreria client Java per Hub eventi è disponibile nel repository centrale di Maven.

		<dependency>
		    <groupId>com.azure</groupId>
		    <artifactId>azure-messaging-eventhubs</artifactId>
		    <version>5.18.0</version>
		</dependency>
		<dependency>
		    <groupId>com.azure</groupId>
		    <artifactId>azure-identity</artifactId>
		    <version>1.11.2</version>
		    <scope>compile</scope>
		</dependency>

Nota

Aggiornare la versione alla versione più recente pubblicata nel repository Maven.

Autenticare l'app in Azure

Questo argomento di avvio rapido illustra due modi per connettersi a Hub eventi di Azure: senza password e stringa di connessione. La prima opzione mostra come usare l'entità di sicurezza in Microsoft Entra ID e il controllo degli accessi in base al ruolo per connettersi a uno spazio dei nomi di Hub eventi. Non è necessario preoccuparsi di avere stringa di connessione hardcoded nel codice o in un file di configurazione o in un'archiviazione sicura come Azure Key Vault. La seconda opzione mostra come usare un stringa di connessione per connettersi a uno spazio dei nomi di Hub eventi. Se non si ha familiarità con Azure, è possibile trovare l'opzione stringa di connessione più semplice da seguire. È consigliabile usare l'opzione senza password in applicazioni e ambienti di produzione reali. Per altre informazioni, consultare Autenticazione e autorizzazione. Per altre informazioni sull'autenticazione senza password, vedere la pagina di panoramica.

Assegnare ruoli all'utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che si connette a Hub eventi di Azure disponga delle autorizzazioni corrette. Per inviare e ricevere messaggi, è necessario il ruolo di proprietario dei dati Hub eventi di Azure. Per assegnare a se stessi questo ruolo, è necessario il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azioneMicrosoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo nella pagina di panoramica dell'ambito.

L'esempio seguente assegna il Azure Event Hubs Data Owner ruolo all'account utente, che fornisce l'accesso completo alle risorse di Hub eventi di Azure. In uno scenario reale, seguire il principio dei privilegi minimi per concedere agli utenti solo le autorizzazioni minime necessarie per un ambiente di produzione più sicuro.

Ruoli predefiniti di Azure per Hub eventi di Azure

Per Hub eventi di Azure, la gestione degli spazi dei nomi e di tutte le risorse correlate tramite il portale di Azure e l'API di gestione delle risorse di Azure è già protetta usando il modello di controllo degli accessi in base al ruolo di Azure. Azure offre i ruoli predefiniti di Azure seguenti per autorizzare l'accesso a uno spazio dei nomi di Hub eventi:

  • Hub eventi di Azure Proprietario dati: consente l'accesso ai dati allo spazio dei nomi di Hub eventi e alle relative entità (code, argomenti, sottoscrizioni e filtri)
  • Hub eventi di Azure Mittente dati: usare questo ruolo per concedere al mittente l'accesso allo spazio dei nomi di Hub eventi e alle relative entità.
  • Hub eventi di Azure Ricevitore dati: usare questo ruolo per concedere al ricevitore l'accesso allo spazio dei nomi di Hub eventi e alle relative entità.

Per creare un ruolo personalizzato, vedere Diritti necessari per le operazioni di Hub eventi.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà un minuto o due. In rari casi, possono essere necessari fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nella portale di Azure individuare lo spazio dei nomi di Hub eventi usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM) selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    A screenshot showing how to assign a role.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Azure Event Hubs Data Owner e selezionare il risultato corrispondente. Scegliere quindi Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain ) e quindi scegliere Seleziona nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi rivedi e assegna per completare il processo.

Scrivere codice per inviare messaggi all'hub eventi

Aggiungere una classe denominata Sender e includere il codice seguente nella classe:

Importante

  • Aggiornare <NAMESPACE NAME> con il nome dello spazio dei nomi di Hub eventi.
  • Aggiornare <EVENT HUB NAME> con il nome dell'hub eventi.
package ehubquickstart;

import com.azure.messaging.eventhubs.*;
import java.util.Arrays;
import java.util.List;

import com.azure.identity.*;

public class SenderAAD {

    // replace <NAMESPACE NAME> with the name of your Event Hubs namespace.
    // Example: private static final String namespaceName = "contosons.servicebus.windows.net";
    private static final String namespaceName = "<NAMESPACE NAME>.servicebus.windows.net";

    // Replace <EVENT HUB NAME> with the name of your event hub. 
    // Example: private static final String eventHubName = "ordersehub";
    private static final String eventHubName = "<EVENT HUB NAME>";

    public static void main(String[] args) {
        publishEvents();
    }
    /**
     * Code sample for publishing events.
     * @throws IllegalArgumentException if the EventData is bigger than the max batch size.
     */
    public static void publishEvents() {
        // create a token using the default Azure credential        
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .authorityHost(AzureAuthorityHosts.AZURE_PUBLIC_CLOUD)
                .build();

        // create a producer client        
        EventHubProducerClient producer = new EventHubClientBuilder()        
            .fullyQualifiedNamespace(namespaceName)
            .eventHubName(eventHubName)
            .credential(credential)
            .buildProducerClient();

        // sample events in an array
        List<EventData> allEvents = Arrays.asList(new EventData("Foo"), new EventData("Bar"));

        // create a batch
        EventDataBatch eventDataBatch = producer.createBatch();

        for (EventData eventData : allEvents) {
            // try to add the event from the array to the batch
            if (!eventDataBatch.tryAdd(eventData)) {
                // if the batch is full, send it and then create a new batch
                producer.send(eventDataBatch);
                eventDataBatch = producer.createBatch();

                // Try to add that event that couldn't fit before.
                if (!eventDataBatch.tryAdd(eventData)) {
                    throw new IllegalArgumentException("Event is too large for an empty batch. Max size: "
                        + eventDataBatch.getMaxSizeInBytes());
                }
            }
        }
        // send the last batch of remaining events
        if (eventDataBatch.getCount() > 0) {
            producer.send(eventDataBatch);
        }
        producer.close();
    }   
}

Compilare il programma e assicurarsi che non siano presenti errori. Questo programma verrà eseguito dopo l'esecuzione del programma ricevente.

Ricevere eventi

Il codice di questa esercitazione si basa sull'esempio di codice EventProcessorSample in GitHub, che è possibile esaminare per vedere l'applicazione completa in funzione.

Seguire questi consigli quando si usa Archiviazione BLOB di Azure come archivio checkpoint:

  • Usare un contenitore separato per ogni gruppo di consumer. È possibile usare lo stesso account di archiviazione, ma usare un contenitore per ogni gruppo.
  • Non usare il contenitore per altri elementi e non usare l'account di archiviazione per altri elementi.
  • Archiviazione account deve trovarsi nella stessa area in cui si trova l'applicazione distribuita. Se l'applicazione è locale, provare a scegliere l'area più vicina possibile.

Nella pagina Archiviazione account della portale di Azure, nella sezione Servizio BLOB verificare che le impostazioni seguenti siano disabilitate.

  • Spazio dei nomi gerarchico
  • Eliminazione temporanea dei BLOB
  • Controllo delle versioni

Creare un account di archiviazione di Azure e un contenitore BLOB

In questa guida di avvio rapido verrà usata una risorsa di archiviazione di Azure (nello specifico, l'archiviazione BLOB) come archivio di checkpoint. Il checkpoint è un processo mediante il quale un processore di eventi contrassegna o conferma la posizione dell'ultimo evento elaborato correttamente all'interno di una partizione. Il contrassegno di un checkpoint viene in genere eseguito all'interno della funzione che elabora gli eventi. Per altre informazioni sul checkpoint, vedere Processore di eventi.

Seguire questa procedura per creare un account di archiviazione di Azure.

  1. Creare un account di archiviazione di Azure
  2. Creare un contenitore BLOB
  3. Eseguire l'autenticazione nel contenitore BLOB

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. È necessario Archiviazione Collaboratore ai dati BLOB per leggere e scrivere dati BLOB. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina di panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito all'account di archiviazione, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo collaboratore ai dati BLOB Archiviazione all'account utente, che fornisce sia l'accesso in lettura che in scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nella portale di Azure individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM) selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    A screenshot showing how to assign a storage account role.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Archiviazione Collaboratore dati BLOB e selezionare il risultato corrispondente e quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain ) e quindi scegliere Seleziona nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi rivedi e assegna per completare il processo.

Aggiungere le librerie di Hub eventi al progetto Java

Aggiungere le dipendenze seguenti nel file pom.xml.

	<dependencies>
		<dependency>
		    <groupId>com.azure</groupId>
		    <artifactId>azure-messaging-eventhubs</artifactId>
		    <version>5.15.0</version>
		</dependency>
		<dependency>
		    <groupId>com.azure</groupId>
		    <artifactId>azure-messaging-eventhubs-checkpointstore-blob</artifactId>
		    <version>1.16.1</version>
		</dependency>
		<dependency>
		    <groupId>com.azure</groupId>
		    <artifactId>azure-identity</artifactId>
		    <version>1.8.0</version>
		    <scope>compile</scope>
		</dependency>	
	</dependencies>
  1. Aggiungere le istruzioni seguenti import all'inizio del file Java.

    import com.azure.messaging.eventhubs.*;
    import com.azure.messaging.eventhubs.checkpointstore.blob.BlobCheckpointStore;
    import com.azure.messaging.eventhubs.models.*;
    import com.azure.storage.blob.*;
    import java.util.function.Consumer;
    
    import com.azure.identity.*;
    
  2. Creare una classe denominata Receiver e aggiungere le variabili di stringa seguenti alla classe. Sostituire i segnaposto con i valori corretti.

    Importante

    Sostituire i segnaposto con i valori corretti.

    • <NAMESPACE NAME> con il nome dello spazio dei nomi di Hub eventi.
    • <EVENT HUB NAME> con il nome dell'hub eventi nello spazio dei nomi .
    private static final String namespaceName = "<NAMESPACE NAME>.servicebus.windows.net";
    private static final String eventHubName = "<EVENT HUB NAME>";
    
  3. Aggiungere il metodo main seguente alla classe.

    Importante

    Sostituire i segnaposto con i valori corretti.

    • <STORAGE ACCOUNT NAME>con il nome dell'account Archiviazione di Azure.
    • <CONTAINER NAME> con il nome del contenitore BLOB nell'account di archiviazione
    // create a token using the default Azure credential
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .authorityHost(AzureAuthorityHosts.AZURE_PUBLIC_CLOUD)
            .build();
    
    // Create a blob container client that you use later to build an event processor client to receive and process events
    BlobContainerAsyncClient blobContainerAsyncClient = new BlobContainerClientBuilder()
            .credential(credential)
            .endpoint("https://<STORAGE ACCOUNT NAME>.blob.core.windows.net")
            .containerName("<CONTAINER NAME>")
            .buildAsyncClient();
    
    // Create an event processor client to receive and process events and errors.
    EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
        .fullyQualifiedNamespace(namespaceName)
        .eventHubName(eventHubName)
        .consumerGroup(EventHubClientBuilder.DEFAULT_CONSUMER_GROUP_NAME)
        .processEvent(PARTITION_PROCESSOR)
        .processError(ERROR_HANDLER)
        .checkpointStore(new BlobCheckpointStore(blobContainerAsyncClient))            
        .credential(credential)
        .buildEventProcessorClient();
    
    System.out.println("Starting event processor");
    eventProcessorClient.start();
    
    System.out.println("Press enter to stop.");
    System.in.read();
    
    System.out.println("Stopping event processor");
    eventProcessorClient.stop();
    System.out.println("Event processor stopped.");
    
    System.out.println("Exiting process");  
    
  1. Aggiungere i due metodi helper (PARTITION_PROCESSOR e ERROR_HANDLER) che elaborano gli eventi e gli errori alla classe Receiver.

    public static final Consumer<EventContext> PARTITION_PROCESSOR = eventContext -> {
        PartitionContext partitionContext = eventContext.getPartitionContext();
        EventData eventData = eventContext.getEventData();
    
        System.out.printf("Processing event from partition %s with sequence number %d with body: %s%n",
            partitionContext.getPartitionId(), eventData.getSequenceNumber(), eventData.getBodyAsString());
    
        // Every 10 events received, it will update the checkpoint stored in Azure Blob Storage.
        if (eventData.getSequenceNumber() % 10 == 0) {
            eventContext.updateCheckpoint();
        }
    };
    
    public static final Consumer<ErrorContext> ERROR_HANDLER = errorContext -> {
        System.out.printf("Error occurred in partition processor for partition %s, %s.%n",
            errorContext.getPartitionContext().getPartitionId(),
            errorContext.getThrowable());
    };
    
  2. Compilare il programma e assicurarsi che non siano presenti errori.

Eseguire le applicazioni

  1. Eseguire prima l'applicazione Receiver .

  2. Eseguire quindi l'applicazione Sender .

  3. Nella finestra Applicazione ricevitore verificare di visualizzare gli eventi pubblicati dall'applicazione Sender.

    Starting event processor
    Press enter to stop.
    Processing event from partition 0 with sequence number 331 with body: Foo
    Processing event from partition 0 with sequence number 332 with body: Bar
    
  4. Premere INVIO nella finestra dell'applicazione ricevente per arrestare l'applicazione.

    Starting event processor
    Press enter to stop.
    Processing event from partition 0 with sequence number 331 with body: Foo
    Processing event from partition 0 with sequence number 332 with body: Bar
    
    Stopping event processor
    Event processor stopped.
    Exiting process
    

Passaggi successivi

Vedere gli esempi seguenti in GitHub: