Usar esquema JSON com aplicativos Apache Kafka

Artigo
05/22/2024

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

Nesse caso de uso, um aplicativo produtor Kafka usa o esquema JSON armazenado no Registro de Esquema do Azure para, serializar o evento e publicá-los em um hub de tópico/evento Kafka nos 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 o esquema JSON, que é armazenado no Registro de Esquema do Azure. Diagrama mostrando a serialização/desserialização de esquema para aplicativos Kafka usando o esquema JSON.

Pré-requisitos

Se você é novo nos Hubs de Eventos do Azure, consulte Visão geral dos Hubs de Eventos antes de fazer este início rápido.

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

Se não tiver uma subscrição 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+.
- Transferir e instalar um arquivo binário Maven.
- Git
Clone o Registro de Esquema do Azure para o repositório Kafka .

Criar um hub de eventos

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

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

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

Criar um esquema

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

Crie um grupo de esquemas 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 nome de esquema: Microsoft.Azure.Data.SchemaRegistry.example.CustomerInvoice usando o seguinte conteúdo de 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 produtor e consumidor Kafka a acessar os recursos do Registro de Esquema do Azure. Para habilitá-lo, você precisa registrar seu aplicativo cliente com um locatário do Microsoft Entra no portal do Azure.

Para registrar um aplicativo 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á:

use.managed.identity.credential - indica que as credenciais MSI devem ser usadas, devem ser usadas para VM habilitada para MSI
managed.identity.clientId - se especificado, cria credenciais MSI com determinado ID de cliente managed.identity.resourceId - se especificado, cria credenciais MSI com determinado ID de recurso

Adicionar usuário à função Leitor do 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 de 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 Controle de acesso (IAM) no menu à esquerda.
Na página Controle de 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 selecione Avançar na parte inferior da página.
Use o link + Selecionar membros para adicionar o example-app aplicativo que você criou na etapa anterior à função e, em seguida, selecione Avançar.
Na página Rever + atribuir, selecione Rever + atribuir.

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

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

Para atualizar a configuração do Kafka Producer, 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 para o produtor em src/main/resources/app.properties usando a configuração relacionada ao registro de esquema e o aplicativo 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 azure-schema-registry-for-kafka/tree/master/java/json/samples/kafka-consumer .

Para aplicativos de produtor e consumidor 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"
    }
  }
}

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

Para executar o aplicativo produtor 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 do esquema JSON ou registros genéricos. Para o modo de registros específicos, você precisa primeiro gerar as classes no esquema do produtor usando o seguinte comando maven:
```
mvn generate-sources
```

Em seguida, você pode executar o aplicativo produtor usando os seguintes comandos.

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 solicita que você escolha o cenário do 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ê 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

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

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

Você pode executar o aplicativo consumidor para que ele possa consumir registros específicos do esquema JSON ou registros genéricos. Para o modo de registros específicos, você precisa primeiro gerar as classes no esquema do produtor usando o seguinte comando maven:
```
mvn generate-sources
```

Em seguida, você pode executar o aplicativo consumidor usando o seguinte comando.

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 solicita que você escolha o cenário do 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 de dados e a desserialização bem-sucedidos, você 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}

Clean up resources (Limpar recursos)

Exclua o namespace Hubs de Eventos ou exclua o grupo de recursos que contém o namespace.

Partilhar via