Usare lo schema JSON con applicazioni Apache Kafka

Articolo
05/22/2024

Questa esercitazione illustra uno scenario in cui si usano schemi JSON per serializzare e deserializzare eventi usando Registro schemi di Azure in Hub eventi.

In questo caso d'uso un'applicazione producer Kafka usa lo schema JSON archiviato nel Registro schemi di Azure per serializzare l'evento e pubblicarli in un hub di argomenti/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 dello schema JSON, archiviato nel Registro schemi di Azure. Diagramma che mostra la serializzazione/de-serializzazione dello schema per le applicazioni Kafka usando lo schema JSON.

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 di avvio rapido: 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 lo schema JSON come tipo di serializzazione.

In tale gruppo di schemi creare un nuovo schema JSON con il nome dello schema: Microsoft.Azure.Data.SchemaRegistry.example.CustomerInvoice usando il contenuto dello schema seguente.

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CustomerInvoice",
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string"
    },
    "merchantId": {
      "type": "string"
    },
    "transactionValueUsd": {
      "type": "integer"
    },
    "userId": {
      "type": "string"
    }
  }
}

Registrare un'applicazione per accedere al registro schemi

È possibile usare Microsoft Entra ID per autorizzare il producer Kafka e l'applicazione consumer ad accedere alle risorse del Registro schemi di Azure. Per abilitarla, è necessario registrare 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 managed.identity.resourceId specificato. Se specificato, compila le credenziali MSI con un ID 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 registro schemi 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 producer e consumer Kafka con i dettagli dell'applicazione Microsoft Entra e con le informazioni del Registro di sistema dello schema.

Per aggiornare la configurazione di Kafka Producer, passare ad azure-schema-registry-for-kafka/tree/master/java/json/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 usando la configurazione correlata allo schema e l'applicazione Microsoft Entra creata nel passaggio precedente 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/json/samples/kafka-consumer .

Per le applicazioni producer e consumer Kafka, viene usato lo schema JSON seguente:

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CustomerInvoice",
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string"
    },
    "merchantId": {
      "type": "string"
    },
    "transactionValueUsd": {
      "type": "integer"
    },
    "userId": {
      "type": "string"
    }
  }
}

Uso del producer Kafka con la convalida dello schema JSON

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

È possibile eseguire l'applicazione producer in modo che possa produrre record specifici dello schema JSON o record generici. 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.
```
Enter case number:
1 - produce SpecificRecords
```

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.KafkaJsonSpecificRecord - Sent Order Invoice 0
INFO com.azure.schemaregistry.samples.producer.KafkaJsonSpecificRecord - Sent Order Invoice 1
INFO com.azure.schemaregistry.samples.producer.KafkaJsonSpecificRecord - Sent Order Invoice 2

Uso del consumer Kafka con la convalida dello schema JSON

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

È possibile eseguire l'applicazione consumer in modo che possa utilizzare record specifici dello schema JSON o record generici. 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 questo argomento di avvio rapido, è possibile scegliere l'opzione 1: utilizzare SpecificRecords.
```
Enter case number:
1 - consume SpecificRecords
```

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.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 0, merchantId=Merchant Id 0, transactionValueUsd=0, userId=User Id 0}
INFO com.azure.schemaregistry.samples.consumer.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 1, merchantId=Merchant Id 1, transactionValueUsd=1, userId=User Id 1}
INFO com.azure.schemaregistry.samples.consumer.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 2, merchantId=Merchant Id 2, transactionValueUsd=2, userId=User Id 2}

Pulire le risorse

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

Condividi tramite