Compartir a través de

Biblioteca cliente de Apache Avro del Registro de esquemas de Azure para .NET: versión 1.0.0

  • Artículo

Azure Schema Registry es un servicio de repositorio de esquemas hospedado por Azure Event Hubs, lo que proporciona almacenamiento de esquemas, control de versiones y administración. Este paquete proporciona un serializador Avro capaz de serializar y deserializar cargas que contienen identificadores de esquema del Registro de esquema y datos serializados de Avro.

Introducción

Instalar el paquete

Instale la biblioteca Apache Avro del Registro de esquemas de Azure para .NET con NuGet:

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

Requisitos previos

Si necesita crear un espacio de nombres de Event Hubs, puede usar Azure Portal o Azure PowerShell.

Puede usar Azure PowerShell para crear el espacio de nombres de Event Hubs con el siguiente comando:

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

Autenticar el cliente

Para interactuar con el servicio Azure Schema Registry, deberá crear una instancia de la clase Client del Registro de esquema . Para crear este cliente, necesitará credenciales de recursos de Azure y el nombre de host del espacio de nombres de Event Hubs.

Obtener credenciales

Para adquirir credenciales authenicated y empezar a interactuar con los recursos de Azure, consulte la guía de inicio rápido aquí.

Obtención del nombre de host del espacio de nombres de Event Hubs

La manera más sencilla es usar el Azure Portal y navegar al espacio de nombres de Event Hubs. En la pestaña Información general, verá Host name. Copie el valor de este campo.

Creación de SchemaRegistryClient

Una vez que tenga las credenciales de recurso de Azure y el nombre de host del espacio de nombres de Event Hubs, puede crear schemaRegistryClient. También necesitará el paquete Azure.Identity para crear la credencial.

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

Conceptos clave

serializer

Esta biblioteca proporciona un serializador , SchemaRegistryAvroSerializer, que interactúa con EventData eventos. SchemaRegistryAvroSerializer utiliza schemaRegistryClient para enriquecer los EventData eventos con el identificador de esquema para el esquema usado para serializar los datos.

Este serializador requiere la biblioteca apache Avro. Los tipos de carga que acepta este serializador incluyen GenericRecord e ISpecificRecord.

Ejemplos

A continuación se muestran ejemplos de lo que está disponible a través de SchemaRegistryAvroSerializer. Hay métodos sincronizados y asincrónicos disponibles para estas operaciones. En estos ejemplos se usa una clase Employee.cs generada de Apache Avro creada con este esquema:

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

Puede encontrar detalles sobre cómo generar una clase mediante la biblioteca de Apache Avro en la documentación de Avro C#.

Serialización y deserialización de datos mediante el modelo EventData del centro de eventos

Para serializar una EventData instancia con información de Avro, puede hacer lo siguiente:

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

Para deserializar un EventData evento que está consumiendo:

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

También puede usar métodos genéricos para serializar y deserializar los datos. Esto puede ser más conveniente si no está creando una biblioteca sobre el serializador Avro, ya que no tendrá que preocuparse por la viralidad de los genéricos:

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 forma similar, para deserializar:

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

Serialización y deserialización de datos mediante MessageContent directamente

También es posible serializar y deserializar mediante MessageContent. Use esta opción si no está integrando con ninguna de las bibliotecas de mensajería que funcionan con 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);

Solución de problemas

Si se producen errores al comunicarse con el servicio Registro de esquemas, estos errores se producirán como requestFailedException. El serializador solo se comunicará con el servicio la primera vez que encuentre un esquema (al serializar) o un identificador de esquema (al deserializar). Los errores relacionados con tipos de contenido no válidos se producirán como .FormatException Los errores relacionados con esquemas no válidos se producirán como , Exceptiony la InnerException propiedad contendrá la excepción subyacente que se produjo desde la biblioteca de Apache Avro. Este tipo de error normalmente se detectaría durante las pruebas y no se debe controlar en el código. Los errores relacionados con esquemas incompatibles se producirán como con Exception la InnerException propiedad establecida en la excepción subyacente de la biblioteca de Apache Avro.

Pasos siguientes

Consulte Azure Schema Registry para más información.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones