Convalidare gli schemi per le applicazioni Apache Kafka usando Avro (Java)

Articolo
03/14/2024

In questa guida introduttiva viene illustrato come convalidare l'evento dalle applicazioni Apache Kafka usando il Registro schemi di Azure per l’Hub eventi.

In questo caso d'uso un'applicazione producer Kafka usa lo schema Avro archiviato nel Registro schemi di Azure per serializzare l'evento ed effettuare la pubblicazione in un argomento o un hub eventi Kafka in Hub eventi di Azure. Il consumer Kafka deserializza gli eventi utilizzati da Hub eventi. A tale scopo, usa l'ID schema dell'evento e lo schema Avro, archiviato nel Registro schemi di Azure.

Diagram showing schema serialization/de-serialization for Kafka applications using Avro schema.

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:

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Nell'ambiente di sviluppo installare i componenti seguenti:
- Java Development Kit (JDK) 1.7+.
- Scaricare e installare un archivio binario Maven.
- Git
Clonare il registro schemi di Azure per il repository Kafka.

Creare un hub eventi

Seguire le istruzioni della guida introduttiva: Creare uno spazio dei nomi di Hub eventi e un hub eventi per creare uno spazio dei nomi di Hub eventi e un hub eventi. Seguire quindi le istruzioni riportate in Ottenere la stringa di connessione per ottenere una stringa di connessione allo spazio dei nomi di Hub eventi.

Prendere nota delle impostazioni seguenti usate nella guida introduttiva corrente:

stringa di connessione per lo spazio dei nomi di Hub eventi
Nome dell'hub eventi

Creare uno schema

Seguire le istruzioni riportate in Creare schemi utilizzando il Registro schemi per creare un gruppo di schemi e uno schema.

Creare un gruppo di schemi denominato contoso-sg utilizzando il portale del Registro schemi. Usare Avro come tipo di serializzazione e Nessuna per la modalità di compatibilità.

In tale gruppo di schemi creare un nuovo schema Avro con il nome dello schema: Microsoft.Azure.Data.SchemaRegistry.example.Order utilizzando il contenuto dello schema seguente.

{
  "namespace": "Microsoft.Azure.Data.SchemaRegistry.example",
  "type": "record",
  "name": "Order",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "amount",
      "type": "double"
    },
    {
      "name": "description",
      "type": "string"
    }
  ]
}

Registrare un'applicazione per accedere al registro schemi

È possibile usare Microsoft Entra ID per autorizzare l'applicazione consumer e il producer Kafka ad accedere alle risorse del Registro schemi di Azure registrando l'applicazione client con un tenant Di Microsoft Entra dal portale di Azure.

Per registrare un'applicazione Microsoft Entra denominata example-app, vedere Registrare l'applicazione con un tenant di Microsoft Entra.

tenant.id: imposta l'ID tenant dell'applicazione
client.id: imposta l'ID client dell'applicazione
client.secret: imposta il segreto client per l'autenticazione

Se si usa l'identità gestita, è necessario:

use.managed.identity.credential : indica che è consigliabile usare le credenziali MSI per la macchina virtuale abilitata per l'identità del servizio gestito
managed.identity.clientId: se specificato, compila le credenziali MSI con l'ID client specificato
managed.identity.resourceId: se specificato, compila le credenziali MSI con l'ID della risorsa specificato

Aggiungere un utente al ruolo lettore del Registro schemi

Aggiungere l'account utente al ruolo Lettore del Registro schemi a livello di spazio dei nomi. È inoltre possibile usare il ruolo Collaboratore del Registro schemi, ma non è necessario per questa guida introduttiva.

Nella pagina Spazio dei nomi di Hub eventi, selezionare Controllo di accesso (IAM) nel menu a sinistra.
Nella pagina Controllo di accesso (IAM), selezionare + Aggiungi ->Aggiungi assegnazione di ruolo nel menu.
Nella pagina Tipo di assegnazione, selezionare Avanti.
Nella pagina Ruoli, selezionare Lettore del Registro schemi (anteprima) e quindi selezionare Avanti nella parte inferiore della pagina.
Usare il collegamento + Seleziona membri per aggiungere l'applicazione example-app creata nel passaggio precedente al ruolo e quindi selezionare Avanti.
Nella pagina Rivedi + assegna, selezionare Rivedi + assegna.

Aggiornare la configurazione dell'applicazione client delle applicazioni Kafka

È necessario aggiornare la configurazione client delle applicazioni consumer e consumer Kafka con la configurazione correlata all'applicazione Microsoft Entra creata e alle informazioni del Registro schemi.

Per aggiornare la configurazione del producer Kafka, passare ad azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-producer.

Aggiornare la configurazione dell'applicazione Kafka in src/main/resources/app.properties seguendo la guida introduttiva di Kafka per Hub eventi.
Aggiornare i dettagli di configurazione per il producer in src/main/resources/app.properties utilizzando la configurazione correlata al registro schemi e l'applicazione Microsoft Entra creata in precedenza come indicato di seguito:
```
schema.group=contoso-sg
schema.registry.url=https://<NAMESPACENAME>.servicebus.windows.net

 tenant.id=<>
 client.id=<>
 client.secret=<>
```
Seguire le stesse istruzioni e aggiornare anche la configurazione azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-consumer.

Per le applicazioni consumer e producer Kafka, viene utilizzato lo schema Avro seguente:

{
  "namespace": "com.azure.schemaregistry.samples",
  "type": "record",
  "name": "Order",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "amount",
      "type": "double"
    },
    {
      "name": "description",
      "type": "string"
    }
  ]
}

Uso del producer Kafka con la convalida dello schema Avro

Per eseguire l'applicazione producer Kafka, passare ad azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-producer.

È possibile eseguire l'applicazione producer in modo che possa produrre record generici o record specifici di Avro. Per la modalità record specifica è necessario prima generare le classi in base allo schema producer utilizzando il comando maven seguente:
```
mvn generate-sources
```

È quindi possibile eseguire l'applicazione producer usando i comandi seguenti.

mvn clean package
mvn -e clean compile exec:java -Dexec.mainClass="com.azure.schemaregistry.samples.producer.App"

Al termine dell'esecuzione dell'applicazione producer, viene richiesto di scegliere lo scenario producer. Per questa guida introduttiva, è possibile scegliere l'opzione 1: produrre SpecificRecords Avro.
```
Enter case number:
1 - produce Avro SpecificRecords
2 - produce Avro GenericRecords
```

Al termine della serializzazione e della pubblicazione dei dati, nell'applicazione producer verranno visualizzati i log della console seguenti:

INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-0", "amount": 10.0, "description": "Sample order 0"}
INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-1", "amount": 11.0, "description": "Sample order 1"}
INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-2", "amount": 12.0, "description": "Sample order 2"}

Utilizzo del consumer Kafka con la convalida dello schema Avro

Per eseguire l'applicazione consumer Kafka, passare ad azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-consumer.

È possibile eseguire l'applicazione consumer in modo che possa utilizzare record generici o record specifici di Avro. Per la modalità record specifica è necessario prima generare le classi in base allo schema producer utilizzando il comando maven seguente:
```
mvn generate-sources
```

È quindi possibile eseguire l'applicazione consumer utilizzando il comando seguente.

mvn clean package
mvn -e clean compile exec:java -Dexec.mainClass="com.azure.schemaregistry.samples.consumer.App"

Al termine dell'esecuzione dell'applicazione consumer, viene richiesto di scegliere lo scenario producer. Per questa guida introduttiva, è possibile scegliere l'opzione 1: utilizzare SpecificRecords Avro.
```
Enter case number:
1 - consume Avro SpecificRecords
2 - consume Avro GenericRecords
```

Al termine dell'utilizzo e della deserializzazione dei dati, verranno visualizzati i log della console seguenti nell'applicazione producer:

INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-0", "amount": 10.0, "description": "Sample order 0"}
INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-1", "amount": 11.0, "description": "Sample order 1"}
INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-2", "amount": 12.0, "description": "Sample order 2"}

Pulire le risorse

Eliminare lo spazio dei nomi di Hub eventi o eliminare il gruppo di risorse che contiene lo spazio dei nomi.