Valider avec un schéma Avro lors d’événements de diffusion en continu à l’aide des kits de développement logiciel (SDK) .NET Event Hubs (AMQP)

Article
04/26/2023

Dans ce guide de démarrage, vous apprendrez comment recevoir des événements d’Event Hub et lui en envoyer avec une validation de schéma à l’aide de la bibliothèque .NET Azure.Messaging.EventHubs.

Notes

Fonctionnalité d’Event Hubs, Azure Schema Registry fournit un référentiel central pour les schémas pour les applications pilotées par les événements et centré sur la messagerie. Il offre aux producteurs et aux consommateurs la flexibilité nécessaire pour échanger des données sans avoir à gérer et partager le schéma entre eux. Il fournit également une infrastructure de gouvernance simple pour les schémas réutilisables et définit la relation entre les schémas par le biais d’une construction de regroupement (groupes de schémas). Pour plus d’informations, consultez Azure Schema Registry dans Event Hubs.

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.
Microsoft Visual Studio 2022. La bibliothèque cliente Azure Event Hubs utilise les nouvelles fonctionnalités introduites dans C# 8.0. Vous pouvez toujours utiliser la bibliothèque avec les versions précédentes du langage C#, mais la nouvelle syntaxe n’est pas disponible. Pour utiliser la syntaxe complète, nous vous recommandons d’effectuer la compilation avec la version 3.0 ou une version ultérieure du kit SDK .NET Core et la version du langagelatest. Si vous utilisez Visual Studio, les versions antérieures à Visual Studio 2019 ne sont pas compatibles avec les outils nécessaires à la génération de projets C# 8.0. Visual Studio 2019, y compris l’édition Community gratuite, est téléchargeable ici.

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 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 Avro comme type de sérialisation et Aucun pour le mode de compatibilité.

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

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

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 (préversion), puis sélectionnez Suivant en bas de la page.
Cliquez sur le lien + Sélectionner des membres pour ajouter votre compte d’utilisateur au rôle, puis sélectionnez Suivant.
Sur la page Vérifier + attribuer, sélectionnez Vérifier + attribuer.

Générer des événements pour Event hubs avec validation de schéma

Créer une application console pour un producteur d’événements

Démarrez Visual Studio 2019.
Sélectionnez Créer un projet.
Dans la boîte de dialogue Créer un projet, effectuez les étapes suivantes : Si vous ne voyez pas cette boîte de dialogue, sélectionnez Fichier dans le menu, sélectionnez Nouveau, puis Projet.
1. Sélectionnez C# en guise de langage de programmation.
2. Sélectionnez Console comme type de l’application.
3. Sélectionnez Application console dans la liste des résultats.
4. Ensuite, sélectionnez Suivant.
Entrez OrderProducer comme nom de projet, SRQuickStart comme nom de solution, puis sélectionnez OK pour créer le projet.

Ajout du package NuGet Event Hubs

Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package à partir du menu.

Exécutez les commandes suivantes pour installer les packages Azure.Messaging.EventHubs et autres packages NuGet. Appuyez sur ENTRÉE pour exécuter la dernière commande.

Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity
Install-Package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro
Install-Package Azure.ResourceManager.Compute

Authentifiez les applications de producteur pour la connexion à Azure via Visual Studio comme indiqué ici.
Connectez-vous à Azure à l’aide du compte d’utilisateur membre du rôle Schema Registry Reader au niveau de l’espace de noms. Pour obtenir des informations sur les rôles du registre de schémas, consultez Azure Schema Registry dans Event Hubs.

Génération de code à l’aide du schéma Avro

Pour créer un fichier appelé Order.avsc, utilisez le même contenu que celui utilisé pour créer le schéma. Enregistrez le fichier dans le dossier du projet ou de la solution.
Vous pouvez ensuite utiliser ce fichier de schéma pour générer du code pour .NET. Vous pouvez utiliser n’importe quel outil de génération de code externe, tel que avrogen, pour la génération de code. Par exemple, vous pouvez exécuter avrogen -s .\Order.avsc . pour générer du code.
Une fois que vous avez généré du code, le fichier nommé Order.cs s’affiche dans le dossier \Microsoft\Azure\Data\SchemaRegistry\example. Pour le schéma Avro ci-dessus, le projet génère les types C# dans l’espace de noms Microsoft.Azure.Data.SchemaRegistry.example.
Ajoutez le fichier Order.cs au projet OrderProducer.

Écriture de code pour sérialiser et envoyer des événements au hub d’événements

Ajoutez le code suivant au fichier Program.cs. Pour plus d’informations, consultez les commentaires du code. Les étapes générales du code sont les suivantes :

Créez un client producteur que vous pouvez utiliser pour envoyer des événements à un Event Hub.
Créez un client du registre de schémas que vous pouvez utiliser pour sérialiser et valider des données dans un objet Order.
Créez un objet Order à l’aide du type Order généré.
Utilisez le client du registre de schémas pour sérialiser l’objet Order en EventData.
Créez un lot d’événements.
Ajoutez les données d’événement au lot d’événements.
Utilisez le client producteur pour envoyer le lot d’événements à l’Event Hub.

using Azure.Data.SchemaRegistry;
using Azure.Identity;
using Microsoft.Azure.Data.SchemaRegistry.ApacheAvro;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;

using Microsoft.Azure.Data.SchemaRegistry.example;

// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// The Event Hubs client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when events are being published or read regularly.
EventHubProducerClient producerClient;

// Create a producer client that you can use to send events to an event hub
producerClient = new EventHubProducerClient(connectionString, eventHubName);

// Create a schema registry client that you can use to serialize and validate data.  
var schemaRegistryClient = new SchemaRegistryClient(schemaRegistryEndpoint, new DefaultAzureCredential());

// Create an Avro object serializer using the Schema Registry client object. 
var serializer = new SchemaRegistryAvroSerializer(schemaRegistryClient, schemaGroup, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

// Create a new order object using the generated type/class 'Order'. 
var sampleOrder = new Order { id = "1234", amount = 45.29, description = "First sample order." };
EventData eventData = (EventData)await serializer.SerializeAsync(sampleOrder, messageType: typeof(EventData));

// Create a batch of events 
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

// Add the event data to the event batch. 
eventBatch.TryAdd(eventData);

// Send the batch of events to the event hub. 
await producerClient.SendAsync(eventBatch);
Console.WriteLine("A batch of 1 order has been published.");

Remplacez les valeurs d’espace réservé suivantes par les valeurs réelles.

EVENTHUBSNAMESPACECONNECTIONSTRING : chaîne de connexion pour l’espace de noms Event Hubs
EVENTHUBNAME : nom de l’Event Hub
EVENTHUBSNAMESPACENAME : nom de l’espace de noms Event Hubs
SCHEMAGROUPNAME : nom du groupe de schémas

// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

Générez le projet et vérifiez qu’il ne présente pas d’erreurs.
Exécutez le programme et attendez le message de confirmation.
```
A batch of 1 order has been published.
```
Sur le Portail Azure, vous pouvez vérifier que le hub d’événements a reçu les événements. Basculez vers l’affichage Messages dans la section Métriques. Actualisez la page pour mettre à jour le graphique. Cela peut prendre quelques secondes pour indiquer que les messages ont été reçus.

Consommer des événements à partir d’Event Hubs avec validation de schéma

Cette section montre comment écrire une application console .NET Core qui reçoit des événements à partir d’un Event Hub et utilise le registre de schémas pour désérialiser les données d’événement.

Autres composants requis

Créez le compte de stockage à utiliser pour le processeur d’événements.

Créer une application consommateur

Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur la solution SRQuickStart, pointez sur Ajouter, puis sélectionnez Nouveau projet.
Sélectionnez Application console, puis Suivant.
Entrez OrderConsumer pour Nom du projet, puis sélectionnez Créer.
Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur OrderConsumer, puis sélectionnez Définir comme projet de démarrage.

Ajout du package NuGet Event Hubs

Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package à partir du menu.
Dans la fenêtre Console du gestionnaire de package, vérifiez que OrderConsumer est sélectionné pour le projet par défaut. Si ce n’est pas le cas, utilisez la liste déroulante pour sélectionner OrderConsumer.

Exécutez la commande suivante pour installer les packages NuGet requis. Appuyez sur ENTRÉE pour exécuter la dernière commande.

Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity
Install-Package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro
Install-Package Azure.ResourceManager.Compute

Authentifiez les applications de producteur pour la connexion à Azure via Visual Studio comme indiqué ici.
Connectez-vous à Azure à l’aide du compte d’utilisateur membre du rôle Schema Registry Reader au niveau de l’espace de noms. Pour obtenir des informations sur les rôles du registre de schémas, consultez Azure Schema Registry dans Event Hubs.
Ajoutez le fichier Order.cs que vous avez généré lors de la création de l’application de producteur au projet OrderConsumer.
Cliquez avec le bouton droit sur le projet OrderConsumer, puis sélectionnez Définir comme projet de démarrage.

Écrire du code pour recevoir des événements et les désérialiser à l’aide du registre de schémas

Ajoutez le code suivant au fichier Program.cs. Pour plus d’informations, consultez les commentaires du code. Les étapes générales du code sont les suivantes :

Créez un client consommateur que vous pouvez utiliser pour envoyer des événements à un Event Hub.
Créez un client de conteneur d’objets blob pour le conteneur d’objets blob dans le stockage Blob Azure.
Créez un client de processeur d’événements et inscrivez les gestionnaires d’événements et d’erreurs.
Dans le gestionnaire d’événements, créez un client du registre de schémas que vous pouvez utiliser pour désérialiser les données d’événement dans un objet Order.
Désérialisez les données d’événement dans un objet Order à l’aide du sérialiseur.
Imprimez les informations sur la commande reçue.

using Azure.Data.SchemaRegistry;
using Azure.Identity;
using Microsoft.Azure.Data.SchemaRegistry.ApacheAvro;
using Azure.Storage.Blobs;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;

using Microsoft.Azure.Data.SchemaRegistry.example;


// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// connection string for the Azure Storage account
const string blobStorageConnectionString = "AZURESTORAGECONNECTIONSTRING";

// name of the blob container that will be userd as a checkpoint store
const string blobContainerName = "BLOBCONTAINERNAME";

// Create a blob container client that the event processor will use 
BlobContainerClient storageClient = new BlobContainerClient(blobStorageConnectionString, blobContainerName);

// Create an event processor client to process events in the event hub
EventProcessorClient processor = new EventProcessorClient(storageClient, EventHubConsumerClient.DefaultConsumerGroupName, connectionString, eventHubName);

// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;

// Start the processing
await processor.StartProcessingAsync();

// Wait for 30 seconds for the events to be processed
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the processing
await processor.StopProcessingAsync();

static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Create a schema registry client that you can use to serialize and validate data.  
    var schemaRegistryClient = new SchemaRegistryClient(schemaRegistryEndpoint, new DefaultAzureCredential());

    // Create an Avro object serializer using the Schema Registry client object. 
    var serializer = new SchemaRegistryAvroSerializer(schemaRegistryClient, schemaGroup, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

    // Deserialized data in the received event using the schema 
    Order sampleOrder = (Order)await serializer.DeserializeAsync(eventArgs.Data, typeof(Order));

    // Print the received event
    Console.WriteLine($"Received order with ID: {sampleOrder.id}, amount: {sampleOrder.amount}, description: {sampleOrder.description}");

       await eventArgs.UpdateCheckpointAsync(eventArgs.CancellationToken);
    }

    static Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
    // Write details about the error to the console window
    Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
    Console.WriteLine(eventArgs.Exception.Message);
    return Task.CompletedTask;
}

Remplacez les valeurs d’espace réservé suivantes par les valeurs réelles.

EVENTHUBSNAMESPACE-CONNECTIONSTRING : chaîne de connexion pour l’espace de noms Event Hubs
EVENTHUBNAME : nom de l’Event Hub
EVENTHUBSNAMESPACENAME : nom de l’espace de noms Event Hubs
SCHEMAGROUPNAME : nom du groupe de schémas
AZURESTORAGECONNECTIONSTRING : chaîne de connexion pour un compte de stockage Azure
BLOBCONTAINERNAME : nom du conteneur d’objets blob

// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACE-CONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// Azure storage connection string
const string blobStorageConnectionString = "AZURESTORAGECONNECTIONSTRING";

// Azure blob container name
const string blobContainerName = "BLOBCONTAINERNAME";

Générez le projet et vérifiez qu’il ne présente pas d’erreurs.
Exécutez l’application réceptrice.
Vous devriez voir un message indiquant que les événements ont été reçus.
```
Received order with ID: 1234, amount: 45.29, description: First sample order.
```
Ces événements sont les trois événements que vous avez envoyés au hub d’événements en exécutant le programme émetteur.

Exemples

Consultez l’article Lisez-moi dans notre dépôt GitHub.

Nettoyer les ressources

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

Étapes suivantes

Consulter la bibliothèque cliente du Registre de schémas Azure pour .NET

Partager via

Valider avec un schéma Avro lors d’événements de diffusion en continu à l’aide des kits de développement logiciel (SDK) .NET Event Hubs (AMQP)

Prérequis

Créer un hub d’événements

Créer un schéma

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

Générer des événements pour Event hubs avec validation de schéma

Créer une application console pour un producteur d’événements

Ajout du package NuGet Event Hubs

Génération de code à l’aide du schéma Avro

Écriture de code pour sérialiser et envoyer des événements au hub d’événements

Consommer des événements à partir d’Event Hubs avec validation de schéma

Autres composants requis

Créer une application consommateur

Ajout du package NuGet Event Hubs

Écrire du code pour recevoir des événements et les désérialiser à l’aide du registre de schémas

Exemples

Nettoyer les ressources

Étapes suivantes

Commentaires

Commentaires

Ressources supplémentaires