Criar um assunto

Neste documento, descrevemos como criar um assunto em um registro de esquema. Um assunto é um contêiner lógico para diferentes versões de um esquema. Ao criar um assunto pela primeira vez, você também cria a primeira versão do esquema para ele.

É possível criar um assunto de uma das seguintes maneiras:

Implícito (padrão): o comportamento padrão de muitos clientes produtores e consumidores é criar automaticamente um esquema que não existe quando o cliente se conecta. O assunto e a versão que fazem referência ao esquema também são criados automaticamente. Isso é conveniente, mas pode levar a possíveis inconsistências nos dados se vários clientes criarem versões simultaneamente.
Explícito (recomendado): nesse método, cada esquema precisa ser criado no registro antes que um cliente produtor ou consumidor possa usá-lo. É possível usar o console Google Cloud ou a API Managed Kafka para fazer isso.

Esse comportamento precisa ser configurado nas configurações do cliente. Consulte a documentação da biblioteca de cliente do serializador ou desserializador para mais detalhes.

Antes de começar

Saiba mais sobre a visão geral do esquema.
Crie um registro de esquema se ainda não tiver um.
Entenda as referências de esquema.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar um assunto, peça ao administrador para conceder a você o papel do IAM de Editor do Managed Kafka Schema Registry (roles/managedkafka.schemaRegistryEditor) no projeto ou no registro de esquema. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar um assunto. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar um assunto:

Conceda essa permissão no contexto principal ou padrão: managedkafka.versions.create

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

O papel de nível superior Administrador do registro de esquema do Kafka gerenciado (roles/managedkafka.schemaRegistryAdmin) também inclui as permissões para criar e gerenciar versões de assunto.

Para mais informações sobre os papéis predefinidos disponíveis para o Managed Service para Apache Kafka, consulte a documentação de controle de acesso.

Criar um assunto ou a primeira versão de um esquema

Ao criar um assunto, você também cria a primeira versão dele. Essa primeira versão cria um novo esquema ou é uma referência a um esquema existente.

Console

No console do Google Cloud , acesse a página Registros de esquema.

Acessar "Registros de esquema"
Clique no nome do registro de esquema em que você quer criar um assunto.
Clique em Criar assunto.
Em Nome do assunto, insira um nome exclusivo.

O nome precisa começar com uma letra e conter apenas letras, números e os seguintes caracteres especiais: traço (-), ponto (.), sublinhado (_), til (~), porcentagem (%) ou sinal de adição (+). O nome de um assunto é imutável.

Para mais informações sobre como escolher um nome de assunto, consulte Estratégias de nomenclatura de assunto.
Em Contexto, escolha ou crie um contexto. Os contextos funcionam como namespaces para organizar seus assuntos e esquemas, oferecendo isolamento entre diferentes grupos.
- Para usar um contexto atual, selecione-o na lista Contexto. O contexto padrão é exibido como (default context).
- Para criar um contexto, siga estas etapas:
  1. Selecione Criar contexto na lista Contexto.
  2. No campo Nome do contexto, insira um nome para o contexto.
    
    O nome precisa começar com uma letra e conter apenas letras, números e os seguintes caracteres especiais: traço (-), ponto (.), sublinhado (_), til (~), porcentagem (%) ou sinal de adição (+). O nome de um contexto é imutável.
  3. Clique em Salvar.
Em Tipo de esquema, selecione Avro ou Buffer de protocolo.
No campo Definição de esquema, insira a definição do esquema. O formato do esquema precisa corresponder ao tipo de esquema. Não inclua informações sensíveis, como informações de identificação pessoal (PII) ou dados de segurança, nos nomes dos campos do esquema.
Se o esquema usar ou depender de estruturas de dados definidas em outros esquemas no registro de esquema, siga estas etapas:
1. Clique em Adicionar referência de esquema.
2. No campo Nome de referência, insira o nome de referência do esquema referenciado.
3. Na lista Assunto, selecione o assunto que contém o esquema referenciado.
4. Na lista Versão, selecione o número da versão do esquema referenciado.
5. Clique em OK.
Repita essas etapas para cada esquema referenciado.
Clique em Criar.

REST

A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token.

Os exemplos de API REST a seguir criam a primeira versão de um assunto.

Para criar um assunto no contexto padrão, faça uma solicitação POST para o URI especificado usando o método projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Como alternativa, se você estiver usando um contexto específico, inclua-o no URI da coleção de assuntos usando o método projects.locations.schemaRegistries.contexts.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Substitua:

PROJECT_ID (obrigatório): ID do projeto do Google Cloud.
LOCATION (obrigatório): a Google Cloud região em que o registro de esquema existe.
REGISTRY_ID (obrigatório): o ID do registro de esquema de destino.
CONTEXT_ID (opcional): o ID do contexto que contém o assunto. Use . para o contexto padrão se quiser ser explícito. Caso contrário, omita /contexts/CONTEXT_ID para usar o contexto padrão de forma implícita.

O nome precisa começar com uma letra e conter apenas letras, números e os seguintes caracteres especiais: traços -, pontos ., sublinhados _, sinais diacríticos ~, porcentagens % ou sinais de adição +. O nome de um contexto é imutável.
SUBJECT_ID (obrigatório): o ID do novo assunto em que a primeira versão será criada.

O nome precisa começar com uma letra e conter apenas letras, números e os seguintes caracteres especiais: traços -, pontos ., sublinhados _, sinais diacríticos ~, porcentagens % ou sinais de adição +. O nome de um assunto é imutável.

Corpo da solicitação:

Inclua um objeto JSON no corpo da solicitação especificando os detalhes do esquema:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Substitua:

YOUR_SCHEMA_DEFINITION_STRING (obrigatório): uma string que contém o payload da definição do esquema.

Não inclua informações sensíveis, como informações de identificação pessoal (PII) ou dados de segurança nos nomes dos campos do esquema.
schemaType (opcional): o tipo do esquema. Pode ser AVRO ou PROTOBUF. Se omitido, o padrão será AVRO.
references (opcional): uma matriz de objetos que definem os esquemas referenciados por este esquema.
- REFERENCE_NAME: o nome usado para referenciar o outro esquema na definição deste esquema.
- REFERENCED_SUBJECT_ID: o ID do assunto do esquema referenciado.
- REFERENCED_VERSION_NUMBER: o número da versão específica do esquema do assunto referenciado.
versionId, schemaId: campos opcionais geralmente processados pelo serviço. Para a primeira versão de um assunto, versionId será "1".

Se a solicitação for bem-sucedida e o esquema for válido e passar nas verificações de compatibilidade, se configurado, a API vai retornar um código de status 200 OK. O corpo da resposta contém o ID do esquema usado pela versão criada, que é diferente do ID da versão.

Para mais informações, consulte a documentação da API REST.

A seguir

Apache Kafka® é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.