Usar o esquema JSON com aplicativos Apache Kafka

Artigo
05/27/2024

Este tutorial explica um cenário em que você usa esquemas JSON para serializar e desserializar o evento usando o Registro de Esquema do Azure nos Hubs de Eventos.

Nesse caso de uso, um aplicativo produtor do Kafka usa o esquema JSON 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 JSON, que é armazenado no Registro de Esquema do Azure. Diagrama que mostra a serialização/desserialização do esquema para aplicativos Kafka usando o esquema JSON.

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:

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Em seu ambiente de desenvolvimento, instale os seguintes componentes:
- Java Development Kit (JDK) 1.7+.
- Realizar o download e instalar um armazenamento binário Maven
- Git
Clone o repositório do Registro de esquema do Azure para Kafka.

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.

Crie um grupo de esquema chamado contoso-sg usando o portal do registro de esquema. Use o Esquema JSON como o tipo de serialização.

Nesse grupo de esquemas, crie um novo esquema JSON com o nome do esquema Microsoft.Azure.Data.SchemaRegistry.example.CustomerInvoice usando o seguinte conteúdo do esquema.

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CustomerInvoice",
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string"
    },
    "merchantId": {
      "type": "string"
    },
    "transactionValueUsd": {
      "type": "integer"
    },
    "userId": {
      "type": "string"
    }
  }
}

Registrar um aplicativo para acessar o registro de esquema

Você pode usar o Microsoft Entra ID para autorizar seu aplicativo de produtor e consumidor Kafka a acessar recursos do registro de esquema do Azure. Para habilitá-lo, você precisa registrar 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 de cliente managed.identity.resourceId - se especificada, cria a credencial MSI com determinada ID de 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.

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

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

Você precisa atualizar a configuração do cliente dos aplicativos de produtor e consumidor Kafka com os detalhes do aplicativo do Microsoft Entra e com as informações do registro de esquema.

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

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.
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 que você criou na etapa anterior da seguinte maneira:
```
schema.group=contoso-sg
schema.registry.url=https://<NAMESPACENAME>.servicebus.windows.net

 tenant.id=<>
 client.id=<>
 client.secret=<>
```
Siga as mesmas instruções e atualize também a configuração do azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-consumer.

Para aplicativos de produtor e consumidor do Kafka, o seguinte esquema JSON é usado:

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CustomerInvoice",
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string"
    },
    "merchantId": {
      "type": "string"
    },
    "transactionValueUsd": {
      "type": "integer"
    },
    "userId": {
      "type": "string"
    }
  }
}

Usar o produtor Kafka com validação de esquema JSON

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

Você pode executar o aplicativo produtor para que ele possa produzir registros específicos ou genéricos do Esquema JSON. 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
```

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"

Após a execução bem-sucedida do aplicativo 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.
```
Enter case number:
1 - produce SpecificRecords
```

Após a serialização e publicação de dados bem-sucedidas, você deverá ver os seguintes logs de console em seu aplicativo produtor:

INFO com.azure.schemaregistry.samples.producer.KafkaJsonSpecificRecord - Sent Order Invoice 0
INFO com.azure.schemaregistry.samples.producer.KafkaJsonSpecificRecord - Sent Order Invoice 1
INFO com.azure.schemaregistry.samples.producer.KafkaJsonSpecificRecord - Sent Order Invoice 2

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

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

Você pode executar o aplicativo consumidor para que ele possa produzir registros específicos ou genéricos do Esquema JSON. 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
```

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"

Após a execução bem-sucedida do aplicativo 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.
```
Enter case number:
1 - consume SpecificRecords
```

Após o consumo e desserialização de dados bem-sucedidos, você deverá ver os seguintes logs de console em seu aplicativo produtor:

INFO com.azure.schemaregistry.samples.consumer.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 0, merchantId=Merchant Id 0, transactionValueUsd=0, userId=User Id 0}
INFO com.azure.schemaregistry.samples.consumer.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 1, merchantId=Merchant Id 1, transactionValueUsd=1, userId=User Id 1}
INFO com.azure.schemaregistry.samples.consumer.KafkaJsonSpecificRecord - Invoice received: {invoiceId=Invoice 2, merchantId=Merchant Id 2, transactionValueUsd=2, userId=User Id 2}

Limpar os recursos

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

Compartilhar via