Um Google Cloud recurso é qualquer componente que você cria ou usa no o Google Cloud. Esses recursos formam os blocos de construção dos aplicativos e sistemas em execução na plataforma.
Os recursos no serviço gerenciado para Apache Kafka incluem o seguinte:
Cluster
Tópico
Grupo de consumidores
ACL
Registro de esquema
Contexto (em um registro de esquema)
Assunto (em um registro de esquema ou contexto)
Versão (versões de um esquema em um assunto)
Esquema (identificado por ID, associado a um ou vários assuntos e versões)
Para mais informações sobre a nomeação geral de recursos Google Cloud , consulte Nomes de recursos. A API de registro de esquema para o serviço gerenciado para Apache Kafka foi projetada para compatibilidade com uma API de código aberto existente. Portanto, algumas convenções de nomenclatura podem ser diferentes dos padrões típicos da API.
Formato de nomeação de recursos
Confira os formatos dos diferentes recursos:
Cluster:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}Tópico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}Grupo de consumidores:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}ACL:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}Registro de esquema:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}Contexto:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}Assunto:
- No contexto padrão:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID} - Em um contexto específico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}
- No contexto padrão:
Esquema (identificado por ID):
- No contexto padrão:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID} - Em um contexto específico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}
- No contexto padrão:
Versão (identificada pelo número da versão em um assunto):
- No contexto padrão:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID} - Em um contexto específico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
- No contexto padrão:
Confira uma análise de cada componente nas próximas seções.
ID do projeto
O valor precisa ser o ID do projeto ou o número do projeto, disponível em
o Google Cloud console. Por exemplo, my-cool-project é um ID do projeto, enquanto 123456789123 é um número do projeto.
Local
O valor precisa ser um dos locais com suporte no serviço gerenciado para Apache Kafka. Para conferir uma lista dos locais disponíveis, consulte Locais do serviço gerenciado para Apache Kafka.
ID
ID é o segmento final no caminho do recurso. Variáveis como
{CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID},
{SCHEMA_REGISTRY_ID}, {CONTEXT_ID} e
{SUBJECT_ID} precisam obedecer às seguintes diretrizes:
Não começar com a string
googComeçar com uma letra
Restrições de tamanho:
IDs de cluster: conter entre 3 e 255 caracteres.
IDs de tópico e grupo de consumidores: qualquer tamanho permitido pelo Apache Kafka. Os nomes de tópicos do Apache Kafka são limitados a 249 caracteres.
ID do registro de esquema: contém até 255 caracteres.
ID do contexto: contém até 255 caracteres.
ID do assunto: contém até 255 bytes UTF-8.
Restrições de caracteres:
IDs de cluster: precisam corresponder ao regex
^[a-z]([-a-z0-9]*[a-z0-9])?. Isso significa letras minúsculas, números e hífens. Ele precisa começar com uma letra e não pode terminar com um hífen.IDs de tópico e grupo de consumidores: a validação é realizada pelo Kafka. Os caracteres permitidos são `[a-zA-Z0-9.-], que incluem caracteres alfanuméricos ASCII, pontos (.), sublinhados () e traços (-).
ID do registro de esquema: letras (maiúsculas ou minúsculas), números e sublinhados
_.ID do contexto: letras (maiúsculas ou minúsculas), números e os seguintes caracteres especiais: traços
-, pontos., sublinhados_, til~, porcentagens%ou sinais de adição+.ID do assunto: letras (maiúsculas ou minúsculas), números e os seguintes caracteres especiais: traços
-, pontos., sublinhados_, til~, porcentagens%ou sinais de adição+.
Caracteres especiais
É possível usar os caracteres especiais listados na seção anterior em IDs de recursos sem codificação de URL. No entanto, é preciso garantir que qualquer outro caractere especial seja codificado ou decodificado corretamente quando usado em URLs.
Por exemplo, mi-tópico é um ID inválido se ó não for um caractere permitido
para esse tipo específico de ID de recurso. No entanto, mi-topico seria válido se apenas letras latinas básicas fossem permitidas. Esse formato é importante ao fazer chamadas REST.
Se você estiver fazendo referência a um tópico das bibliotecas de cliente do Kafka, o caminho completo do recurso não será usado. Apenas o nome do tópico será usado. Da mesma forma, ao interagir com esquemas usando integrações de cliente do Kafka, como serializadores ou desserializadores, normalmente você usa o nome do assunto em vez do caminho completo do recurso.
Estratégias de nomeação de assuntos
Ao trabalhar com o registro de esquema, especialmente com integrações de cliente do Kafka, como serializadores e desserializadores, o nome do assunto é fundamental. A estratégia de nomeação de assuntos determina como um esquema é registrado e recuperado do registro de esquema. Diferentes estratégias oferecem níveis variados de flexibilidade e controle sobre a evolução do esquema.
É possível configurar a estratégia de nomeação de assuntos definindo a propriedade key.subject.name.strategy ou value.subject.name.strategy na configuração do cliente do Kafka.
TopicNameStrategy
Essa é a estratégia padrão para bibliotecas de cliente do Kafka de código aberto.
O nome do assunto é derivado diretamente do nome do tópico do Kafka, anexado com key para chaves de mensagem ou value para valores de mensagem. Se auto.register.schema
estiver definido como true, os clientes do produtor vão usar topicName-value ou topicName-key
para um tópico chamado topicName.
Veja alguns exemplos:
- Nome do tópico:
orders - Assunto para valores de mensagem:
orders-value - Assunto para chaves de mensagem:
orders-key
Confira a lista de vantagens de usar TopicNameStrategy:
É uma estratégia simples, o que a torna adequada para muitos casos de uso.
Os esquemas são vinculados diretamente a um tópico, permitindo que você evolua os tipos de registro em um único tópico de forma independente.
Confira a lista de desvantagens de usar TopicNameStrategy:
- Cada tópico só pode processar um tipo de mensagem com base no esquema de valor. Isso acontece porque o nome do assunto é fixo ao nome do tópico. Se você precisar enviar diferentes tipos de registros para o mesmo tópico, essa estratégia não vai funcionar.
RecordNameStrategy
Essa estratégia usa o nome de classe totalmente qualificado do registro Avro ou Protobuf como o nome do assunto.
Veja alguns exemplos:
- Nome do esquema Avro:
com.example.data.Customer - Nome da mensagem Protobuf:
com.example.data.Order - Assunto para o esquema
customer:com.example.data.Customer - Assunto para o esquema
order:com.example.data.Order
Confira a lista de vantagens de usar RecordNameStrategy:
Como o nome do assunto não está vinculado ao tópico, é possível enviar diferentes tipos de registros para o mesmo tópico do Kafka. Isso é possível desde que cada tipo de registro tenha seu próprio nome totalmente qualificado e esquema correspondente registrado.
Um esquema para um tipo de registro específico, como
com.example.common.Address, pode ser usado em vários tópicos, e a evolução dele é gerenciada de forma centralizada em um único assunto.
Confira a lista de desvantagens de usar RecordNameStrategy:
- É necessário usar o mesmo assunto e versão para todos os tópicos que usam um tipo de registro específico. Isso pode ser restritivo se você precisar de versões diferentes do mesmo tipo de registro em tópicos diferentes.
TopicRecordNameStrategy
Essa estratégia combina aspectos de TopicNameStrategy e RecordNameStrategy.
O nome do assunto é uma combinação do nome do tópico do Kafka e do nome de classe totalmente qualificado do registro, formatado como TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.
Veja alguns exemplos:
Tópico:
user-eventsNome totalmente qualificado:
com.example.events.PageViewNome do assunto para essa combinação:
user-events-com.example.events.PageViewOutro tópico:
product-interactionsNome totalmente qualificado:
com.example.events.PageViewNome do assunto para essa combinação:
product-interactions-com.example.events.PageView
Confira a lista de vantagens de usar TopicRecordNameStrategy:
Semelhante a
RecordNameStrategy, é possível enviar diferentes tipos de registros para o mesmo tópico.Ao contrário de
RecordNameStrategy, essa estratégia permite que você evolua o esquema de um tipo de registro específico de forma independente em cada tópico. Isso significa quemy-topic-com.example.project.MyRecordpode evoluir de maneira diferente deanother-topic-com.example.project.MyRecord.
Confira a lista de desvantagens de usar TopicRecordNameStrategy:
- Os nomes de assuntos podem ficar muito longos devido à combinação do nome do tópico e do nome de registro totalmente qualificado.