Schema Registry no Azure Event Hubs

Neste artigo você vai configurar o Schema Registry no Azure Event Hubs com Terraform, criando um schema group Avro com compatibilidade Forward. O Schema Registry no Azure Event Hubs garante que todos os produtores e consumidores concordem com o formato das mensagens — sem schema registry, um produtor que muda o formato de um campo pode quebrar silenciosamente todos os consumidores.

Sumário

• O que é Schema Registry
• Schema Registry no Azure Event Hubs
• Avro vs JSON Schema
• Modos de compatibilidade: Forward e Backward
• Pré-requisitos
• Passo 1 — main.tf: módulo de schema registry
• Passo 2 — Executar o Terraform
• Resultado do apply
• Registrar um schema Avro
• Limitações do SKU Standard
• Troubleshooting
• Próximos passos

O que é Schema Registry

Schema Registry é um serviço centralizado que armazena e valida os schemas (formatos) das mensagens que trafegam em um sistema de mensageria. Sem schema registry, cada produtor e consumidor precisa concordar informalmente sobre o formato das mensagens — e qualquer mudança no produtor pode quebrar consumidores existentes sem aviso. Com schema registry, o schema é um contrato formal: quando um produtor tenta publicar uma mensagem com schema incompatível, o registro rejeita a publicação antes que a mensagem chegue ao event hub.

O Schema Registry no Azure Event Hubs é um serviço nativo do namespace — sem custo adicional no SKU Standard — que suporta dois formatos: Avro (binário, compacto, tipado) e JSON Schema (texto, legível, mais flexível). Para o nosso sistema de pedidos, Avro é a escolha mais eficiente: as mensagens são menores (sem nomes de campos repetidos como em JSON) e o schema garante que o campo pedido_id seja sempre um inteiro.

Schema Registry no Azure Event Hubs

O Schema Registry no Azure Event Hubs é organizado em schema groups — agrupamentos lógicos de schemas relacionados. Um schema group define o tipo de schema (Avro ou JSON) e o modo de compatibilidade que se aplica a todos os schemas dentro do grupo. No SKU Standard, cada namespace suporta até 1 schema group. No SKU Premium, o limite é 10 schema groups.

Para o nosso lab, criamos um único schema group Avro com compatibilidade Forward — adequado para a maioria dos cenários de evolução de schema em produção. O Terraform provisiona o schema group; os schemas individuais (como o schema do evento de pedido) são registrados via REST API após o deploy.

Avro vs JSON Schema

Avro é um formato de serialização binário desenvolvido pelo Apache que usa um schema para descrever a estrutura dos dados. Ao contrário do JSON, as mensagens Avro não incluem os nomes dos campos — apenas os valores binários, na ordem definida pelo schema. Isso resulta em mensagens muito menores: um evento de pedido com 5 campos em Avro tem tipicamente 40-60% do tamanho equivalente em JSON. Para o Schema Registry no Azure Event Hubs, Avro é recomendado quando o throughput de mensagens é alto.

JSON Schema é uma opção mais acessível para equipes que já trabalham com JSON: as mensagens continuam legíveis sem ferramentas especiais e o schema define apenas os tipos e restrições. Use JSON Schema quando a legibilidade e a facilidade de debug são prioridade e o overhead de tamanho das mensagens é aceitável.

Modos de compatibilidade: Forward e Backward

O modo de compatibilidade define o contrato de evolução de schemas no Schema Registry no Azure Event Hubs:

Modo	Definição	Caso de uso
Forward	Novo schema é legível por consumidores com schema antigo	Produtores atualizam antes dos consumidores
Backward	Schema antigo é legível por consumidores com schema novo	Consumidores atualizam antes dos produtores
Full	Compatível em ambas as direções	Restrição mais conservadora, permite atualizações em qualquer ordem
None	Sem verificação de compatibilidade	Labs e experimentos

Para o nosso sistema de e-commerce, Forward é a escolha certa: quando adicionamos um novo campo opcional (como canal_venda) ao schema de pedidos, os consumidores com schema antigo simplesmente ignoram o campo desconhecido. O produtor pode ser atualizado com segurança antes dos consumidores.

Pré-requisitos

O Schema Registry no Azure Event Hubs deste artigo requer o Art. 02 aplicado — o namespace evhns-kafka-blog-castilho-eus deve existir. O módulo faz referência ao ID do namespace via data source.

Passo 1 — main.tf: módulo de schema registry

O módulo terraform-eventhub-schema-modules cria os schema groups dentro do namespace. No SKU Standard, apenas 1 schema group é suportado — o módulo já trata essa limitação:

data "azurerm_eventhub_namespace" "kafka" {
  name                = "evhns-kafka-blog-castilho-eus"
  resource_group_name = "rg-kafka-blog-castilho-eus"
}

module "schema_registry" {
  source       = "../../terraform-eventhub-schema-modules"
  namespace_id = data.azurerm_eventhub_namespace.kafka.id

  schema_groups = [
    {
      name                 = "sg-avro-blog-castilho-eus"
      schema_type          = "Avro"
      schema_compatibility = "Forward"
    },
  ]
}

O argumento namespace_id (e não o nome do namespace) é necessário para o recurso azurerm_eventhub_schema_group. O data source do namespace resolve o ID automaticamente.

Passo 2 — Executar o Terraform

cp backend.hcl.example backend.hcl
terraform init -backend-config=backend.hcl
terraform plan
terraform apply

Resultado do apply

Após o apply, o Schema Registry no Azure Event Hubs está disponível no namespace:

Recurso	Nome	Detalhe
Schema Group	sg-avro-blog-castilho-eus	Tipo: Avro, Compatibilidade: Forward

Verifique via CLI:

az eventhubs namespace schema-registry list \
  --resource-group rg-kafka-blog-castilho-eus \
  --namespace-name evhns-kafka-blog-castilho-eus \
  --output table

Registrar um schema Avro

Com o schema group criado, registre o schema do evento de pedido via REST API do Schema Registry no Azure Event Hubs. O endpoint usa a mesma autenticação SAS do namespace:

NAMESPACE="evhns-kafka-blog-castilho-eus"
SCHEMA_GROUP="sg-avro-blog-castilho-eus"
SCHEMA_NAME="Pedido"

# Obter token SAS
SAS_TOKEN=$(az eventhubs namespace authorization-rule keys list \
  --resource-group rg-kafka-blog-castilho-eus \
  --namespace-name $NAMESPACE \
  --name RootManageSharedAccessKey \
  --query primaryKey -o tsv)

# Registrar schema
curl -X PUT \
  "https://$NAMESPACE.servicebus.windows.net/$SCHEMA_GROUP/schemas/$SCHEMA_NAME?api-version=2021-10" \
  -H "Authorization: SharedAccessSignature $SAS_TOKEN" \
  -H "Content-Type: application/json; serialization=Avro" \
  -d '{
    "type": "record",
    "name": "Pedido",
    "namespace": "com.castilho.kafka",
    "fields": [
      {"name": "pedido_id", "type": "int"},
      {"name": "produto",   "type": "string"},
      {"name": "quantidade","type": "int"},
      {"name": "timestamp", "type": "long"}
    ]
  }'

Limitações do SKU Standard

O SKU Standard impõe algumas limitações importantes ao Schema Registry no Azure Event Hubs: (1) máximo de 1 schema group por namespace — se você precisar de grupos separados para Avro e JSON, faça upgrade para o SKU Premium; (2) o limite de schemas por grupo é 25 no Standard e 1000 no Premium; (3) não há suporte a schema groups com tipo JSON no SKU Standard de algumas regiões — verifique a disponibilidade antes de escolher JSON Schema em vez de Avro.

No Terraform do Art. 05 dessa série, o schema group JSON foi removido justamente por essa limitação — o SKU Standard só permite 1 grupo, e escolhemos Avro por ser o formato mais eficiente para o caso de uso.

Troubleshooting

Erro: SchemaGroupQuotaExceeded — o SKU Standard já tem 1 schema group. Execute terraform destroy no schema group existente antes de criar um novo, ou faça upgrade do namespace para Premium.

Schema incompatível rejeitado — se tentar registrar uma versão nova do schema que viola a compatibilidade Forward (ex: remover um campo obrigatório), o registro retorna 409 Conflict. Revise as mudanças — campos novos devem ter valores default em Avro para manter compatibilidade Forward.

Próximos passos

Com o Schema Registry no Azure Event Hubs configurado e o schema Avro de pedidos registrado, o último artigo da série configura o monitoramento completo com Azure Managed Grafana e Log Analytics — dashboards de throughput, latência e consumer group lag em tempo real.

Interessado em saber mais sobre artigos relacionados ao Microsoft Azure CLIQUE AQUI

🚀 Vamos nos conectar?

Não perca nenhuma oportunidade! Cadastre-se nas minhas redes e no canal do YouTube para receber conteúdos de TI, Cloud, Azure, Kubernetes e DevOps em primeira mão.

📺 YouTube: Jefferson Castilho – MVP💼 LinkedIn: Jefferson Castilho 👥 Facebook: Jefferson Castilho

Dica: No Facebook, todos os artigos do blog são publicados automaticamente. Vale a pena curtir!

---

💬 Dúvidas ou Problemas?

Com o intuito de ajudar a comunidade, caso você tenha dúvidas ou encontre problemas na execução dos comandos deste artigo, deixe um comentário abaixo. Responderei o mais breve possível!

Muito obrigado pela visita e até o próximo post!

Jefferson Castilho Especialista em Cloud & DevOps.

---

Este guia técnico é exclusivo do Blog do Castilho. Explore nossa para mais conteúdos sobre IA e Cloud.