Utiliser un schéma JSON avec des applications Apache Kafka

Article
10/20/2023

Ce tutoriel vous guide tout au long d’un scénario où vous utilisez des schémas JSON pour sérialiser et désérialiser un événement avec Azure Schema Registry dans Event Hubs.

Dans ce cas d’usage, une application producteur JSON utilise le schéma Avro stocké dans Azure Schema Registry pour sérialiser l’événement et le publier dans une rubrique/un hub d’événements Kafka au sein d’Azure Event Hubs. Le consommateur Kafka désérialise les événements qu’il consomme à partir d’Event Hubs. Pour cela, il utilise l’ID de schéma de l’événement et le schéma JSON, qui est stocké dans Azure Schema Registry. Diagramme montrant la sérialisation/désérialisation pour les applications Kafka avec un schéma JSON.

Prérequis

Si vous débutez avec Azure Event Hubs, consultez la vue d’ensemble d’Event Hubs avant de suivre ce guide de démarrage rapide.

Pour effectuer ce démarrage rapide, vous avez besoin de ce qui suit :

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Dans votre environnement de développement, installez les composants suivants :
- Java Development Kit (JDK) 1.7+.
- Téléchargez et installez une archive binaire Maven.
- Git
Clonez le dépôt Azure Schema Registry pour Kafka.

Créer un hub d’événements

Suivez les instructions fournie dans Démarrage rapide : Créer un espace de noms Event Hubs et un Event Hub pour créer un espace de noms Event Hubs et un Event Hub. Suivez ensuite les instructions fournies dans Obtenir la chaîne de connexion pour obtenir une chaîne de connexion à votre espace de noms Event Hubs.

Notez les paramètres suivants que vous allez utiliser dans le guide de démarrage rapide actuel :

Chaîne de connexion pour l’espace de noms Event Hubs
Nom du Event Hub

Créer un schéma

Suivez les instructions de Créer des schémas à l’aide du registre de schémas pour créer un groupe de schémas et un schéma.

Créez un groupe de schémas nommé contoso-sg à l’aide du portail Registre de schémas. Utilisez Schéma JSON comme type de sérialisation.

Dans ce groupe de schémas, créez un nouveau schéma JSON avec le nom de schéma : Microsoft.Azure.Data.SchemaRegistry.example.CustomerInvoice à l’aide du contenu de schéma suivant.

{
  "$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"
    }
  }
}

Inscrire une application pour accéder au registre de schémas

Vous pouvez utiliser Microsoft Entra ID pour autoriser votre application producteur et consommateur Kafka à accéder aux ressources Azure Schema Registry. Pour ce faire, vous devez inscrire votre application cliente auprès d’un locataire Microsoft Entra à partir du portail Azure.

Pour inscrire une application Microsoft Entra nommée example-app, consultez Inscrire votre application auprès d’un locataire Microsoft Entra.

tenant.id : définit l’ID de locataire de l’application
client.id : définit l’ID client de l’application
client.secret : définit la clé secrète client pour l’authentification

Et si vous utilisez une identité managée, vous avez besoin des éléments suivants :

use.managed.identity.credential : indique que les informations d’identification MSI doivent être utilisées pour une machine virtuelle avec MSI
managed.identity.clientId : si spécifié, génère des informations d’identification MSI avec l’ID client donné managed.identity.resourceId : si spécifié, génère des informations d’identification MSI avec l’ID de ressource donné

Ajouter un utilisateur au rôle Lecteur du registre de schémas

Ajoutez votre compte d’utilisateur au rôle Lecteur du registre de schémas au niveau de l’espace de noms. Vous pouvez également utiliser le rôle Contributeur du registre de schémas, mais ce n’est pas nécessaire pour ce démarrage rapide.

Sur la page Espace de noms Event Hubs, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.
Sur la page Contrôle d’accès (IAM), sélectionnez + Ajouter ->Ajouter une attribution de rôle dans le menu.
Sur la page Type d’affectation, sélectionnez Suivant.
Sur la page Rôles, sélectionnez Lecteur du registre de schémas, puis Suivant en bas de la page.
Utilisez le lien + Sélectionner des membres pour ajouter l’application example-app que vous avez créée à l’étape précédente au rôle, puis sélectionnez Suivant.
Sur la page Vérifier + attribuer, sélectionnez Vérifier + attribuer.

Mettre à jour la configuration de l’application cliente des applications Kafka

Vous devez mettre à jour la configuration cliente des applications producteur et consommateur Kafka avec les détails de l’application Microsoft Entra et avec les informations du registre de schémas.

Pour mettre à jour la configuration du producteur Kafka, accédez à azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-producer.

Mettez à jour la configuration de l’application Kafka dans src/main/resources/app.properties en suivant le guide de démarrage rapide Kafka pour Event Hubs.
Mettez à jour les détails de configuration du producteur dans src/main/resources/app.properties en utilisant la configuration liée au registre de schémas et l’application Microsoft Entra que vous avez créée à l’étape précédente comme suit :
```
schema.group=contoso-sg
schema.registry.url=https://<NAMESPACENAME>.servicebus.windows.net

 tenant.id=<>
 client.id=<>
 client.secret=<>
```
Suivez les mêmes instructions et mettez également à jour la configuration azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-consumer.

Pour les applications producteur et consommateur Kafka, le schéma JSON suivant est utilisé :

{
  "$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"
    }
  }
}

Utilisation du producteur Kafka avec la validation de schéma JSON

Pour exécuter l’application producteur Kafka, accédez à azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-producer.

Vous pouvez exécuter l’application producteur afin qu’elle produise des enregistrements spécifiques au schéma JSON ou des enregistrements génériques. Pour le mode avec enregistrements spécifiques, vous devez d’abord générer les classes sur le schéma producteur avec la commande maven suivante :
```
mvn generate-sources
```

Vous pouvez ensuite exécuter l’application producteur avec les commandes suivantes.

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

Une fois réussie l’exécution de l’application producteur, elle vous invite à choisir le scénario de producteur. Dans le cadre de ce guide de démarrage rapide, vous pouvez choisir l’option 1 : produire des enregistrements spécifiques.
```
Enter case number:
1 - produce SpecificRecords
```

Une fois la sérialisation et la publication des données réussies, vous devez voir les journaux de console suivants dans votre application producteur :

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

Utilisation du consommateur Kafka avec la validation de schéma JSON

Pour exécuter l’application consommateur Kafka, accédez à azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-consumer.

Vous pouvez exécuter l’application consommateur afin qu’elle produise des enregistrements spécifiques au schéma JSON ou des enregistrements génériques. Pour le mode avec enregistrements spécifiques, vous devez d’abord générer les classes sur le schéma producteur avec la commande maven suivante :
```
mvn generate-sources
```

Vous pouvez ensuite exécuter l’application consommateur avec la commande suivante.

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

Une fois l’application consommateur exécutée avec succès, elle vous invite à choisir le scénario de producteur. Dans le cadre de ce démarrage rapide, vous pouvez choisir l’option 1 : consommer des enregistrements spécifiques.
```
Enter case number:
1 - consume SpecificRecords
```

Une fois réussies la consommation et la désérialisation des données, vous devez voir les journaux de console suivants dans votre application producteur :

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}

Nettoyer les ressources

Supprimez l’espace de noms Event Hubs ou supprimez le groupe de ressources contenant l’espace de noms.

Partager via