Bibliothèque de client Apache Avro pour .NET dans le registre de schémas Azure - version 1.0.0

  • Article

Azure Schema Registry est un service de référentiel de schémas hébergé par Azure Event Hubs, qui fournit le stockage des schémas, le contrôle de version et la gestion. Ce package fournit un sérialiseur Avro capable de sérialiser et de désérialiser des charges utiles contenant des identificateurs de schémas du registre de schémas et des données avro-sérialisées.

Prise en main

Installer le package

Installez la bibliothèque Azure Schema Registry Apache Avro pour .NET avec NuGet :

dotnet add package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro

Prérequis

Si vous devez créer un espace de noms Event Hubs, vous pouvez utiliser le portail Azure ou Azure PowerShell.

Vous pouvez utiliser Azure PowerShell pour créer l’espace de noms Event Hubs avec la commande suivante :

New-AzEventHubNamespace -ResourceGroupName myResourceGroup -NamespaceName namespace_name -Location eastus

Authentifier le client

Pour interagir avec le service Azure Schema Registry, vous devez créer un instance de la classe Client Schema Registry. Pour créer ce client, vous avez besoin des informations d’identification de ressource Azure et du nom d’hôte de l’espace de noms Event Hubs.

Récupérer les informations d’identification

Pour acquérir des informations d’identification authentifiées et commencer à interagir avec les ressources Azure, consultez le guide de démarrage rapide ici.

Obtenir le nom d’hôte de l’espace de noms Event Hubs

La méthode implique d’utiliser le Portail Azure et d’accéder à votre espace de noms Event Hubs. Sous l’onglet Vue d’ensemble, vous voyez Host name. Copiez la valeur de ce champ.

Créer schemaRegistryClient

Une fois que vous disposez des informations d’identification de la ressource Azure et du nom d’hôte de l’espace de noms Event Hubs, vous pouvez créer le SchemaRegistryClient. Vous aurez également besoin du package Azure.Identity pour créer les informations d’identification.

// Create a new SchemaRegistry client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
// For more information on Azure.Identity usage, see: https://github.com/Azure/azure-sdk-for-net/blob/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.0/sdk/identity/Azure.Identity/README.md
var schemaRegistryClient = new SchemaRegistryClient(fullyQualifiedNamespace: fullyQualifiedNamespace, credential: new DefaultAzureCredential());

Concepts clés

serializer

Cette bibliothèque fournit un sérialiseur, SchemaRegistryAvroSerializer, qui interagit avec EventData les événements. SchemaRegistryAvroSerializer utilise un SchemaRegistryClient pour enrichir les événements avec l’ID EventData de schéma du schéma utilisé pour sérialiser les données.

Ce sérialiseur nécessite la bibliothèque Apache Avro. Les types de charge utile acceptés par ce sérialiseur incluent GenericRecord et ISpecificRecord.

Exemples

Voici des exemples de ce qui est disponible via le SchemaRegistryAvroSerializer. Il existe des méthodes de synchronisation et asynchrones disponibles pour ces opérations. Ces exemples utilisent une classe Apache Avro Employee.cs générée à l’aide de ce schéma :

{
   "type" : "record",
    "namespace" : "TestSchema",
    "name" : "Employee",
    "fields" : [
        { "name" : "Name" , "type" : "string" },
        { "name" : "Age", "type" : "int" }
    ]
}

Pour plus d’informations sur la génération d’une classe à l’aide de la bibliothèque Apache Avro, consultez la documentation Avro C#.

Sérialiser et désérialiser des données à l’aide du modèle EventData Event Hub

Pour sérialiser un EventData instance avec des informations Avro, vous pouvez effectuer les opérations suivantes :

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = (EventData) await serializer.SerializeAsync(employee, messageType: typeof(EventData));

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

// construct a publisher and publish the events to our event hub
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();
await using var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
await producer.SendAsync(new EventData[] { eventData });

Pour désérialiser un EventData événement que vous consommez :

// construct a consumer and consume the event from our event hub
await using var consumer = new EventHubConsumerClient(EventHubConsumerClient.DefaultConsumerGroupName, fullyQualifiedNamespace, eventHubName, credential);
await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync())
{
    Employee deserialized = (Employee) await serializer.DeserializeAsync(eventData, typeof(Employee));
    Console.WriteLine(deserialized.Age);
    Console.WriteLine(deserialized.Name);
    break;
}

Vous pouvez également utiliser des méthodes génériques pour sérialiser et désérialiser les données. Cela peut être plus pratique si vous ne créez pas de bibliothèque sur le sérialiseur Avro, car vous n’aurez pas à vous soucier de la viralité des génériques :

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

var employee = new Employee { Age = 42, Name = "Caketown" };
EventData eventData = await serializer.SerializeAsync<EventData, Employee>(employee);

// the schema Id will be included as a parameter of the content type
Console.WriteLine(eventData.ContentType);

// the serialized Avro data will be stored in the EventBody
Console.WriteLine(eventData.EventBody);

De même, pour désérialiser :

Employee deserialized = await serializer.DeserializeAsync<Employee>(eventData);
Console.WriteLine(deserialized.Age);
Console.WriteLine(deserialized.Name);

Sérialiser et désérialiser des données en utilisant MessageContent directement

Il est également possible de sérialiser et de désérialiser à l’aide MessageContentde . Utilisez cette option si vous n’effectuez pas d’intégration avec l’une des bibliothèques de messagerie qui fonctionnent avec MessageContent.

var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });
MessageContent content = await serializer.SerializeAsync<MessageContent, Employee>(employee);

Employee deserializedEmployee = await serializer.DeserializeAsync<Employee>(content);

Dépannage

Si vous rencontrez des erreurs lors de la communication avec le service Registre de schémas, ces erreurs sont levées en tant que RequestFailedException. Le sérialiseur communique uniquement avec le service la première fois qu’il rencontre un schéma (lors de la sérialisation) ou un ID de schéma (lors de la désérialisation). Toutes les erreurs liées à Content-Types non valides sont levées en tant que FormatException. Les erreurs liées aux schémas non valides sont levées en tant que Exception, et la InnerException propriété contient l’exception sous-jacente qui a été levée à partir de la bibliothèque Apache Avro. Ce type d’erreur est généralement intercepté pendant le test et ne doit pas être géré dans le code. Toutes les erreurs liées à des schémas incompatibles sont levées en tant que Exception avec la InnerException propriété définie sur l’exception sous-jacente de la bibliothèque Apache Avro.

Étapes suivantes

Pour plus d’informations, consultez Registre de schémas Azure .

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions