Démarrage rapide : 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)

Dans ce guide de démarrage rapide, vous allez apprendre à envoyer et recevoir des événements à partir d’un hub d’événements avec validation de schéma à l’aide de la bibliothèque .NET Azure.Messaging.EventHubs .

Azure Schema Registry est une fonctionnalité d’Event Hubs. Le Registre fournit un référentiel central pour les schémas pour les applications centrées sur les événements et les messages. 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.

Conditions préalables

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 des 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 de compiler avec le Kit de développement logiciel (SDK) .NET Core 3.0 ou version ultérieure et la version du langage définie sur latest.

    Si vous utilisez Visual Studio, les versions antérieures à Visual Studio 2019 ne sont pas compatibles avec les outils nécessaires pour générer des projets C# 8.0. Pour télécharger Visual Studio 2019 ou Visual Studio 2022, y compris l’édition Community gratuite, consultez Visual Studio.

Créer un concentrateur d’événements

Pour créer un espace de noms Event Hubs et un hub d’événements, suivez les instructions de créer un espace de noms Event Hubs et un hub d’événements.

Pour obtenir une chaîne de connexion à votre espace de noms Event Hubs, suivez les instructions de Obtenir la chaîne de connexion.

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

  • Chaîne de connexion pour l’espace de noms Event Hubs
  • Nom du hub d’événements

Créer un schéma

Pour créer un groupe de schémas et un schéma, suivez les instructions de créer des schémas à l’aide du Registre de schémas.

  1. Créez un groupe de schémas nommé contoso-sg à l’aide du portail du Registre de schémas. Utilisez Avro comme type de sérialisation et None pour le mode de compatibilité.

  2. Dans ce groupe de schémas, créez un schéma Avro avec le nom du schéma : Microsoft.Azure.Data.SchemaRegistry.example.Order. Utilisez le 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 guide de démarrage rapide.

  1. Dans la page Espace de noms Event Hubs , dans le menu de gauche, sélectionnez Contrôle d’accès (IAM) .
  2. Dans la page Contrôle d’accès (IAM), sélectionnez + Ajouter une>attribution de rôle.
  3. Dans la page Rôles , sélectionnez Lecteur du Registre de schémas, puis sélectionnez Suivant.
  4. Utilisez le lien + Sélectionner des membres pour ajouter votre compte d’utilisateur au rôle, puis sélectionnez Suivant.
  5. Sur la page Vérifier + attribuer, sélectionnez Vérifier + attribuer.

Produire des événements dans des hubs d’événements avec validation de schéma

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

  1. Démarrez Visual Studio.

  2. Sélectionnez Créer un projet.

  3. Dans la boîte de dialogue de création d’un projet, procédez comme suit. Si cette boîte de dialogue ne s’affiche pas, 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.

      Capture d’écran montrant la boîte de dialogue Nouveau projet Visual Studio.

  4. Entrez OrderProducer pour le nom du projet, SRQuickStart pour le nom de la solution, puis sélectionnez OK pour créer le projet.

Ajout du package NuGet Event Hubs

  1. Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package.

  2. Exécutez les commandes suivantes pour installer Azure.Messaging.EventHubs et d’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

  3. Authentifiez les applications de producteur pour vous connecter à Azure à l’aide de Visual Studio. Pour plus d’informations, consultez Bibliothèque de client Azure Identity pour .NET.

  4. Connectez-vous à Azure à l’aide du compte d’utilisateur membre du rôle Schema Registry Reader au niveau de l’espace de noms. Pour plus d’informations sur les rôles de Registre de schémas, consultez le contrôle d’accès en fonction du rôle Azure.

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

  1. Utilisez le même contenu que celui que vous avez utilisé pour créer le schéma pour créer un fichier nommé Order.avsc. Enregistrez le fichier dans le dossier projet ou solution.
  2. Utilisez 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 qu’avrogen pour la génération de code. Par exemple, exécutez avrogen -s .\Order.avsc . pour générer du code.
  3. Après avoir généré du code, vous voyez le fichier nommé Order.cs dans le \Microsoft\Azure\Data\SchemaRegistry\example dossier. Pour le schéma Avro ici, le projet génère les types C# dans l’espace de noms Microsoft.Azure.Data.SchemaRegistry.example.
  4. Ajoutez le Order.cs fichier au OrderProducer projet.

Écrire du code pour sérialiser et envoyer des événements au hub d’événements

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

    1. Créez un client de producteur que vous pouvez utiliser pour envoyer des événements à un hub d’événements.
    2. Créez un client de Registre de schémas que vous pouvez utiliser pour sérialiser et valider des données dans un Order objet.
    3. Créez un nouvel objet Order en utilisant le type généré Order.
    4. Utilisez le client de Registre de schémas pour sérialiser l’objet Order vers EventData.
    5. Créez un lot d’événements.
    6. Ajoutez les données d’événement au lot d’événements.
    7. Utilisez le client producteur pour envoyer le lot d’événements au hub d’événements.
    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.");

  2. 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 du hub d’événements
    • 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";

  3. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

  4. Exécutez le programme et attendez le message de confirmation.

    A batch of 1 order has been published.

  5. Dans le portail Azure, vous pouvez vérifier que le hub d’événements a reçu les événements. Basculez vers la vue Messages dans la section Métriques . Actualisez la page pour mettre à jour le graphique. La réception des messages peut prendre quelques secondes.

    Image de la page du portail Azure pour vérifier que le hub d’événements a reçu les événements.

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 d’un hub d’événements et utilise le Registre de schémas pour désérialiser les données d’événement.

Conditions préalables supplémentaires

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

Créer une application pour les consommateurs

  1. Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur la solution SRQuickStart , sélectionnez Ajouter, puis Nouveau projet.
  2. Sélectionnez Application console, puis Suivant.
  3. Entrez OrderConsumer pour le nom du projet, puis sélectionnez Créer.
  4. 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

  1. Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package.

  2. 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.

  3. 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

  4. Authentifiez les applications de producteur pour vous connecter à Azure à l’aide de Visual Studio, comme indiqué dans la bibliothèque cliente Azure Identity pour .NET.

  5. Connectez-vous à Azure à l’aide du compte d’utilisateur membre du rôle au niveau de l’espace de noms Schema Registry Reader. Pour plus d’informations sur les rôles de Registre de schémas, consultez le contrôle d’accès en fonction du rôle Azure.

  6. Ajoutez le Order.cs fichier que vous avez généré dans le cadre de la création de l’application de producteur au projet OrderConsumer .

  7. 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

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

    1. Créez un client consommateur que vous pouvez utiliser pour envoyer des événements à un hub d’événements.
    2. Créez un client de conteneur d’objets blob pour le conteneur d’objets blob dans le stockage Blob Azure.
    3. Créez un client de processeur d’événements et inscrivez des gestionnaires d’événements et d’erreurs.
    4. Dans le gestionnaire d’événements, créez un client de registre de schémas que vous pouvez utiliser pour désérialiser les données d’événement dans un Order objet.
    5. Désérialisez les données d’événement dans un Order objet à l’aide du sérialiseur.
    6. 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 used 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;
}

  2. 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 du hub d’événements
    • EVENTHUBSNAMESPACENAME - nom de l’espace de noms Event Hubs
    • SCHEMAGROUPNAME - nom du groupe de schémas
    • AZURESTORAGECONNECTIONSTRING - Chaîne de connexion pour le 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";

  3. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

  4. Exécutez l’application réceptrice.

  5. Vous devez voir un message indiquant que le hub d’événements a reçu les événements.

    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.

Échantillons

Consultez la bibliothèque cliente Apache Avro d’Azure Schema Registry pour .NET.

Nettoyer les ressources

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

Étape suivante

Bibliothèque de client Azure Schema Registry pour .NET

  • Last updated on