Biblioteca de clientes do Apache Avro do Registro de Esquema do Azure para .NET – versão 1.0.0

  • Artigo

O Registro de Esquema do Azure é um serviço de repositório de esquema hospedado por Hubs de Eventos do Azure, fornecendo armazenamento de esquema, controle de versão e gerenciamento. Esse pacote fornece um serializador Avro capaz de serializar e desserializar cargas que contêm identificadores de esquema do Registro de Esquema e dados serializados do Avro.

Introdução

Instalar o pacote

Instale a biblioteca Apache Avro do Registro de Esquema do Azure para .NET com o NuGet:

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

Pré-requisitos

Se você precisar criar um namespace dos Hubs de Eventos, poderá usar o Portal do Azure ou Azure PowerShell.

Você pode usar Azure PowerShell para criar o namespace dos Hubs de Eventos com o seguinte comando:

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

Autenticar o cliente

Para interagir com o serviço registro de esquema do Azure, você precisará criar uma instância da classe Cliente do Registro de Esquema . Para criar esse cliente, você precisará de credenciais de recurso do Azure e do nome do host do namespace dos Hubs de Eventos.

Obter credenciais

Para adquirir credenciais autenticadas e começar a interagir com recursos do Azure, consulte o guia de início rápido aqui.

Obter nome do host do namespace dos Hubs de Eventos

A maneira mais simpliest é usar o portal do Azure e navegar até o namespace dos Hubs de Eventos. Na guia Visão geral, você verá Host name. Copie o valor desse campo.

Criar SchemaRegistryClient

Depois de ter as credenciais de recurso do Azure e o nome do host do namespace dos Hubs de Eventos, você poderá criar o SchemaRegistryClient. Você também precisará do pacote Azure.Identity para criar a 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());

Principais conceitos

serializador

Essa biblioteca fornece um serializador, SchemaRegistryAvroSerializer, que interage com EventData eventos. O SchemaRegistryAvroSerializer utiliza um SchemaRegistryClient para enriquecer os EventData eventos com a ID do esquema para o esquema usado para serializar os dados.

Esse serializador requer a biblioteca do Apache Avro. Os tipos de conteúdo aceitos por esse serializador incluem GenericRecord e ISpecificRecord.

Exemplos

O exemplo a seguir mostra exemplos do que está disponível por meio do SchemaRegistryAvroSerializer. Há métodos de sincronização e assíncrono disponíveis para essas operações. Estes exemplos usam uma classe Do Apache Avro gerada Employee.cs criada usando este esquema:

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

Detalhes sobre como gerar uma classe usando a biblioteca Do Apache Avro podem ser encontrados na Documentação do Avro C#.

Serializar e desserializar dados usando o modelo EventData do Hub de Eventos

Para serializar uma EventData instância com informações do Avro, você pode fazer o seguinte:

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 desserializar um EventData evento que você está consumindo:

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

Você também pode usar métodos genéricos para serializar e desserializar os dados. Isso pode ser mais conveniente se você não estiver criando uma biblioteca sobre o serializador Avro, pois não precisará se preocupar com a viralidade dos 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);

Da mesma forma, para desserializar:

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

Serializar e desserializar dados usando MessageContent diretamente

Também é possível serializar e desserializar usando MessageContent. Use essa opção se você não estiver integrando com nenhuma das bibliotecas de mensagens que funcionam com 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);

Solução de problemas

Se você encontrar erros ao se comunicar com o serviço de Registro de Esquema, esses erros serão gerados como uma RequestFailedException. O serializador só se comunicará com o serviço na primeira vez que encontrar um esquema (ao serializar) ou uma ID de esquema (ao desserializar). Todos os erros relacionados a Tipos de Conteúdo inválidos serão gerados como um FormatException. Erros relacionados a esquemas inválidos serão gerados como um Exceptione a InnerException propriedade conterá a exceção subjacente que foi lançada da biblioteca do Apache Avro. Esse tipo de erro normalmente seria capturado durante o teste e não deve ser tratado no código. Quaisquer erros relacionados a esquemas incompatíveis serão gerados como um Exception com a InnerException propriedade definida como a exceção subjacente da biblioteca do Apache Avro.

Próximas etapas

Consulte Registro de Esquema do Azure para obter informações adicionais.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões