Share via

Azure Schema Registry Apache Avro-Clientbibliothek für .NET – Version 1.0.0

  • Artikel

Azure Schema Registry ist ein von Azure Event Hubs gehosteter Schemarepositorydienst, der Schemaspeicher, Versionsverwaltung und -verwaltung bereitstellt. Dieses Paket bietet einen Avro-Serialisierer, der Nutzlasten serialisieren und deserialisieren kann, die Schemaregistrierungsschemabezeichner und Avro-serialisierte Daten enthalten.

Erste Schritte

Installieren des Pakets

Installieren Sie die Apache Avro-Bibliothek von Azure Schema Registry für .NET mit NuGet:

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

Voraussetzungen

Wenn Sie einen Event Hubs-Namespace erstellen müssen, können Sie das Azure-Portal oder Azure PowerShell verwenden.

Sie können Azure PowerShell verwenden, um den Event Hubs-Namespace mit dem folgenden Befehl zu erstellen:

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

Authentifizieren des Clients

Um mit dem Azure Schema Registry-Dienst zu interagieren, müssen Sie eine instance der SchemaRegistrierungsclientklasse erstellen. Zum Erstellen dieses Clients benötigen Sie Azure-Ressourcenanmeldeinformationen und den Hostnamen des Event Hubs-Namespaces.

Abrufen von Anmeldeinformationen

Informationen zum Abrufen authentifizierter Anmeldeinformationen und zum Starten der Interaktion mit Azure-Ressourcen finden Sie in der Schnellstartanleitung hier.

Abrufen des Hostnamens des Event Hubs-Namespaces

Die einfachste Möglichkeit besteht darin, die Azure-Portal zu verwenden und zu Ihrem Event Hubs-Namespace zu navigieren. Auf der Registerkarte Übersicht wird angezeigt Host name. Kopieren Sie den Wert aus diesem Feld.

Erstellen von SchemaRegistryClient

Sobald Sie über die Anmeldeinformationen der Azure-Ressource und den Hostnamen des Event Hubs-Namespaces verfügen, können Sie schemaRegistryClient erstellen. Sie benötigen auch das Azure.Identity-Paket , um die Anmeldeinformationen zu erstellen.

// 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());

Wichtige Begriffe

serializer

Diese Bibliothek stellt einen Serialisierer, SchemaRegistryAvroSerializer, bereit, der mit EventData Ereignissen interagiert. Der SchemaRegistryAvroSerializer verwendet einen SchemaRegistryClient, um die Ereignisse mit der EventData Schema-ID für das Schema anzureichern, das zum Serialisieren der Daten verwendet wird.

Für dieses Serialisierungsprogramm ist die Apache Avro-Bibliothek erforderlich. Zu den Nutzlasttypen, die von diesem Serialisierungsprogramm akzeptiert werden, gehören GenericRecord und ISpecificRecord.

Beispiele

Im Folgenden finden Sie Beispiele dafür, was über SchemaRegistryAvroSerializerverfügbar ist. Für diese Vorgänge stehen sowohl Synchronisierungsmethoden als auch asynchrone Methoden zur Verfügung. In diesen Beispielen wird eine generierte Apache Avro-Klasse Employee.cs verwendet, die mit diesem Schema erstellt wurde:

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

Details zum Generieren einer Klasse mithilfe der Apache Avro-Bibliothek finden Sie in der Avro C#-Dokumentation.

Serialisieren und Deserialisieren von Daten mithilfe des Event Hub EventData-Modells

Um eine EventData instance mit Avro-Informationen zu serialisieren, können Sie die folgenden Schritte ausführen:

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 });

So deserialisieren Sie ein Von Ihnen genutztes EventData Ereignis:

// 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;
}

Sie können auch generische Methoden verwenden, um die Daten zu serialisieren und deserialisieren. Dies ist möglicherweise bequemer, wenn Sie keine Bibliothek auf dem Avro-Serialisierer erstellen, da Sie sich keine Gedanken über die Viralität von Generika machen müssen:

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);

Analog zum Deserialisieren:

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

Direktes Serialisieren und Deserialisieren von MessageContent Daten

Es ist auch möglich, mit MessageContentzu serialisieren und deserialisieren. Verwenden Sie diese Option, wenn Sie keine der Messagingbibliotheken integrieren, die mit MessageContentfunktionieren.

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);

Problembehandlung

Wenn bei der Kommunikation mit dem Schemaregistrierungsdienst Fehler auftreten, werden diese Fehler als RequestFailedException ausgelöst. Der Serialisierer kommuniziert nur mit dem Dienst, wenn er zum ersten Mal auf ein Schema (beim Serialisieren) oder eine Schema-ID (beim Deserialisieren) stößt. Alle Fehler im Zusammenhang mit ungültigen Inhaltstypen werden als FormatExceptionausgelöst. Fehler im Zusammenhang mit ungültigen Schemas werden als Exceptionausgelöst, und die InnerException -Eigenschaft enthält die zugrunde liegende Ausnahme, die aus der Apache Avro-Bibliothek ausgelöst wurde. Diese Art von Fehler wird normalerweise beim Testen abgefangen und sollte nicht im Code behandelt werden. Alle Fehler im Zusammenhang mit inkompatiblen Schemas werden als eine Exception ausgelöst, wobei die InnerException Eigenschaft auf die zugrunde liegende Ausnahme aus der Apache Avro-Bibliothek festgelegt ist.

Nächste Schritte

Weitere Informationen finden Sie unter Azure Schema Registry .

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe