Registrar uma nova versão do esquema

Depois de criar um assunto, é possível adicionar novas versões a ele. Esse processo é conhecido como registro de uma nova versão de esquema. Cada nova versão representa uma evolução do esquema associado a esse assunto.

Um assunto pode ter várias versões. As versões em um assunto seguem regras de compatibilidade configuráveis para garantir uma evolução segura do esquema. Por exemplo, um assunto pode exigir que todas as mudanças sejam compatíveis com versões anteriores. Um exemplo de mudança compatível com versões anteriores é a adição de um campo opcional. Adicionar um campo obrigatório seria considerado uma mudança incompatível com versões anteriores. Se o assunto estiver configurado para compatibilidade com versões anteriores, essa mudança não será permitida. No entanto, se o assunto estiver configurado para compatibilidade com versões futuras, adicionar um campo obrigatório será aceitável.

As verificações de compatibilidade não são retroativas. Se as regras de compatibilidade forem alteradas para um assunto ou registro de esquema, as versões já existentes no assunto não serão revalidadas com base nas novas regras. Para mais informações sobre compatibilidade, consulte Sobre o tipo de compatibilidade.

Papéis e permissões necessárias

Para receber as permissões necessárias para registrar uma versão de esquema para 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 seu projeto ou no registro de esquema e assunto específicos. 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 registrar uma versão de esquema para 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 registrar uma versão de esquema para 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 Managed Kafka (roles/managedkafka.schemaRegistryAdmin) também inclui essas permissões.

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

Registrar uma nova versão do esquema

Para registrar uma nova versão do esquema, siga estas etapas.

Console

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

    Acessar "Registros de esquema"

  2. Clique no nome do registro de esquema em que você quer registrar uma nova versão.

  3. Em Assuntos neste registro de esquema, clique no nome do assunto.

  4. Na página Detalhes do assunto, clique em Criar versão.

  5. O campo Definição do esquema mostra a definição da versão mais recente. Atualize a definição neste campo para a nova versão. 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.

  6. 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.

  7. Opcional: para verificar se o novo esquema é compatível com a versão anterior, clique em Verificar compatibilidade.

    Se o esquema for compatível, uma marca de seleção vai aparecer. Caso contrário, uma mensagem de erro vai aparecer. Nesse caso, corrija o erro e clique em Verificar compatibilidade novamente.

    A verificação de compatibilidade realizada depende do tipo de compatibilidade do assunto.

  8. Clique em Criar. Se a definição de esquema for válida e passar nas verificações de compatibilidade do assunto, a nova versão vai aparecer em Todas as versões.

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.

Para registrar uma nova versão de esquema para um assunto no contexto padrão, faça uma solicitação POST para o URI específico usando o método projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1/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 versões e use o método projects.locations.schemaRegistries.contexts.subjects.versions.create.

POST https://managedkafka.googleapis.com/v1/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 . (um único ponto) 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.
  • SUBJECT_ID (obrigatório): o ID do assunto em que a nova versão será criada.

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" | "JSON", // 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.

  • schemaType (opcional, dentro do objeto schema): o tipo do esquema. Pode ser AVRO ou PROTOBUF. Se omitido, o padrão será AVRO.

  • references (opcional, dentro do objeto schema): 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 nome do assunto totalmente qualificado do esquema que está sendo referenciado. Por exemplo: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.

    • REFERENCED_VERSION_NUMBER: o número da versão específica (inteiro) do esquema do assunto referenciado.

  • versionId, schemaId: campos opcionais geralmente processados pelo serviço. Ao registrar a versão do esquema, o serviço atribui o próximo número de versão disponível.

Se a solicitação for bem-sucedida, a API vai retornar um código de status 200 OK e um corpo de resposta com o ID do esquema.

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.