Validar esquemas para aplicativos Apache Kafka usando o Avro (Java)

Neste guia de início rápido, exploraremos como validar o evento de aplicativos Apache Kafka usando o Registro de Esquema do Azure para Hubs de Eventos.

Nesse caso de uso, um aplicativo de produtor do Kafka usa o esquema Avro armazenado no Registro de Esquema do Azure para serializar o evento e publicá-lo em um tópico/hub de eventos Kafka no Hubs de Eventos do Azure. O consumidor Kafka desserializa os eventos que consome dos Hubs de Eventos. Para isso, ele usa a ID do esquema do evento e do esquema Avro, armazenada no Registro de Esquema do Azure.

Diagram showing schema serialization/de-serialization for Kafka applications using Avro schema.

Pré-requisitos

Se você estiver conhecendo agora os Hubs de Eventos do Azure, confira Visão geral dos Hubs de Eventos antes de prosseguir com este início rápido.

Para concluir este início rápido, você precisará dos seguintes pré-requisitos:

Criar um Hub de Evento

Siga as instruções do início rápido: Criar um namespace dos Hubs de Eventos e um hub de eventos para criar um namespace dos Hubs de Eventos e um hub de eventos. Depois, siga as instruções em Obter a cadeia de conexão para obter uma cadeia de conexão para seu namespace dos Hubs de Eventos.

Anote as seguintes configurações que você usará no início rápido atual:

  • Cadeia de conexão para o namespace dos Hubs de Eventos
  • Nome do hub de eventos

Criar um esquema

Siga as instruções em Criar esquemas usando o Registro de Esquema para criar um grupo de esquema e um esquema.

  1. Crie um grupo de esquema chamado contoso-sg usando o portal do registro de esquema. Use Avro como o tipo de serialização e Nenhum para o modo de compatibilidade.

  2. Nesse grupo de esquemas, crie um esquema Avro com o nome do esquema Microsoft.Azure.Data.SchemaRegistry.example.Order usando o conteúdo do esquema a seguir.

    {
      "namespace": "Microsoft.Azure.Data.SchemaRegistry.example",
      "type": "record",
      "name": "Order",
      "fields": [
        {
          "name": "id",
          "type": "string"
        },
        {
          "name": "amount",
          "type": "double"
        },
        {
          "name": "description",
          "type": "string"
        }
      ]
    } 
    

Registrar um aplicativo para acessar o registro de esquema

Use o Microsoft Entra ID para autorizar seu aplicativo de produtor e consumidor do Kafka a acessar recursos do Registro de Esquema do Azure, registrando seu aplicativo cliente com um locatário Microsoft Entra do portal do Azure.

Para registrar um aplicativo do Microsoft Entra chamado example-app, consulte Registrar seu aplicativo com um locatário do Microsoft Entra.

  • tenant.id – define a ID do locatário do aplicativo
  • client.id – define a ID do cliente do aplicativo
  • client.secret – define o segredo do cliente para autenticação

E se você estiver usando a identidade gerenciada, precisará de:

  • use.managed.identity.credential - indica que as credenciais MSI devem ser usadas, devem ser usadas para VM habilitada para MSI
  • managed.identity.clientId – se especificada, cria a credencial MSI com determinada ID do cliente
  • managed.identity.resourceId – se especificada, cria a credencial MSI com determinada ID do recurso

Adicionar usuário à função de Leitor de Registro de Esquema

Adicione sua conta de usuário à função Leitor de Registro de Esquema no nível do namespace. Você também pode usar a função Colaborador do Registro de Esquema, mas isso não é necessário para este início rápido.

  1. Na página Namespace de Hubs de Eventos, selecione Gerenciamento de Identidades e Acesso (IAM) no menu à esquerda.
  2. Na página Gerenciamento de Identidades e Acesso (IAM), selecione + Adicionar ->Adicionar atribuição de função no menu.
  3. Na página Tipo de atribuição, selecione Avançar.
  4. Na página Funções, selecione Leitor de Registro de Esquema (versão prévia), e então selecione Avançar na parte inferior da página.
  5. Use o link + Selecionar membros para adicionar o aplicativo example-app que você criou na etapa anterior à função e selecione Avançar.
  6. Na página Examinar + atribuir, selecione Examinar + atribuir.

Atualizar a configuração do aplicativo cliente de aplicativos Kafka

Atualize a configuração do cliente dos aplicativos produtor e consumidor do Kafka com a configuração relacionada ao aplicativo do Microsoft Entra que criamos e com as informações do registro de esquema.

Para atualizar a configuração do Produtor do Kafka, navegue até azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-producer.

  1. Atualize a configuração do aplicativo Kafka em src/main/resources/app.properties seguindo o guia de Início Rápido do Kafka para Hubs de Eventos.

  2. Atualize os detalhes de configuração do produtor em src/main/resources/app.properties usando a configuração relacionada ao registro de esquema e o aplicativo do Microsoft Entra, criado acima da seguinte maneira:

    schema.group=contoso-sg
    schema.registry.url=https://<NAMESPACENAME>.servicebus.windows.net
    
     tenant.id=<>
     client.id=<>
     client.secret=<>
    
  3. Siga as mesmas instruções e atualize também a configuração azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-consumer.

  4. Para aplicativos de produtor e consumidor do Kafka, o seguinte esquema Avro é usado:

    {
      "namespace": "com.azure.schemaregistry.samples",
      "type": "record",
      "name": "Order",
      "fields": [
        {
          "name": "id",
          "type": "string"
        },
        {
          "name": "amount",
          "type": "double"
        },
        {
          "name": "description",
          "type": "string"
        }
      ]
    }
    

Usar o produtor do Kafka com validação de esquema Avro

Para executar o aplicativo de produtor do Kafka, navegue até azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-producer.

  1. Você pode executar o aplicativo de produtor para que ele possa produzir registros específicos ou registros genéricos do Avro. Para o modo de registros específico, você precisará primeiro gerar as classes no esquema produtor usando o seguinte comando do Maven:

    mvn generate-sources
    
  2. Em seguida, você poderá executar o aplicativo produtor usando os comandos a seguir.

    mvn clean package
    mvn -e clean compile exec:java -Dexec.mainClass="com.azure.schemaregistry.samples.producer.App"
    
  3. Após a execução bem-sucedida do aplicativo de produtor, ele solicitará que você escolha o cenário de produtor. Para este início rápido, você pode escolher a opção 1 – produzir SpecificRecords do Avro.

    Enter case number:
    1 - produce Avro SpecificRecords
    2 - produce Avro GenericRecords
    
  4. Após a serialização e publicação de dados bem-sucedidas, você deverá ver os seguintes logs de console em seu aplicativo de produtor:

    INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-0", "amount": 10.0, "description": "Sample order 0"}
    INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-1", "amount": 11.0, "description": "Sample order 1"}
    INFO com.azure.schemaregistry.samples.producer.KafkaAvroSpecificRecord - Sent Order {"id": "ID-2", "amount": 12.0, "description": "Sample order 2"}
    

Usar o consumidor Kafka com validação de esquema Avro

Para executar a configuração do aplicativo de consumidor do Kafka, navegue até azure-schema-registry-for-kafka/tree/master/java/avro/samples/kafka-consumer.

  1. Você pode executar o aplicativo de consumidor para que ele possa produzir registros específicos ou registros genéricos do Avro. Para o modo de registros específico, você precisará primeiro gerar as classes no esquema produtor usando o seguinte comando do Maven:

    mvn generate-sources
    
  2. Em seguida, você poderá executar o aplicativo consumidor usando o comando a seguir.

    mvn clean package
    mvn -e clean compile exec:java -Dexec.mainClass="com.azure.schemaregistry.samples.consumer.App"
    
  3. Após a execução bem-sucedida do aplicativo de consumidor, ele solicitará que você escolha o cenário de produtor. Para este início rápido, você pode escolher a opção 1 – consumir SpecificRecords do Avro.

    Enter case number:
    1 - consume Avro SpecificRecords
    2 - consume Avro GenericRecords
    
  4. Após o consumo e desserialização de dados bem-sucedidos, você deverá ver os seguintes logs de console em seu aplicativo de produtor:

    INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-0", "amount": 10.0, "description": "Sample order 0"}
    INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-1", "amount": 11.0, "description": "Sample order 1"}
    INFO com.azure.schemaregistry.samples.consumer.KafkaAvroSpecificRecord - Order received: {"id": "ID-2", "amount": 12.0, "description": "Sample order 2"}
    

Limpar os recursos

Excluir o namespace dos Hubs de Eventos ou excluir o grupo de recursos que contém o namespace.