Um recurso Google Cloud é qualquer componente que você cria ou usa no Google Cloud. Esses recursos formam os elementos básicos dos aplicativos e sistemas em execução na plataforma.
Os recursos do Serviço gerenciado para Apache Kafka incluem:
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 nomenclatura geral de recursos Google Cloud , consulte Nomes de recursos. A API do registro de esquema do Serviço gerenciado para Apache Kafka foi projetada para ser compatível com uma API de código aberto existente. Por isso, algumas convenções de nomenclatura podem ser diferentes dos padrões típicos de API.
Formato de nomeação de recursos
Confira os formatos dos diferentes recursos:
Cluster:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}Assunto:
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 detalhada de cada componente nas próximas seções.
ID do projeto
O valor precisa ser o ID ou o número do projeto, disponível no console Google Cloud . Por exemplo, my-cool-project é um ID do projeto, enquanto 123456789123 é um número do projeto.
Local
O valor precisa ser um dos locais aceitos pelo Serviço gerenciado para Apache Kafka. Para 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
goog;Começar com uma letra
Restrições de tamanho:
IDs de cluster: têm entre 3 e 255 caracteres.
IDs de tópico e grupo de consumidores: qualquer comprimento 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 à 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 é feita pelo Kafka. Os caracteres permitidos são `[a-zA-Z0-9.-], que incluem 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_, tils~, 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_, tils~, porcentagens%ou sinais de adição+.
ID da ACL
O acl_id define o padrão de recurso a que as entradas de ACL se aplicam. Todas as entradas de ACL na ACL se aplicam ao padrão de recurso codificado no ID da ACL.
acl_id precisa ser estruturado como um dos seguintes:
Para ACLs no cluster:
cluster
Para ACLs em um único recurso no cluster:
topic/{RESOURCE_NAME}consumerGroup/{RESOURCE_NAME}transactionalId/{RESOURCE_NAME}
Para ACLs em todos os recursos que correspondem a um prefixo:
topicPrefixed/{RESOURCE_NAME}consumerGroupPrefixed/{RESOURCE_NAME}transactionalIdPrefixed/{RESOURCE_NAME}
Para ACLs em todos os recursos de um determinado tipo (curinga):
allTopics(representatopic/*)allConsumerGroups(representaconsumerGroup/*)allTransactionalIds(representatransactionalId/*)
{RESOURCE_NAME}: o nome do recurso específico.
Exemplos:
- Para conceder permissões em um tema específico
my-topic:topic/my-topic - Para conceder permissões em todos os tópicos que começam com
test-:topicPrefixed/test- - Para conceder permissões no próprio cluster:
cluster - Para conceder permissões em qualquer grupo:
allConsumerGroups - Para conceder permissões em um ID de transação específico
tx-id:transactionalId/tx-id
Caracteres especiais
É possível usar os caracteres especiais listados na seção anterior em IDs de recursos sem codificação para URLs. Mas, é preciso garantir que os demais caracteres especiais sejam codificados ou decodificados corretamente quando usados 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 referenciando um tópico das bibliotecas de cliente do Kafka, o caminho completo do recurso não será usado. Apenas o nome do tópico é usado. Da mesma forma, ao interagir com esquemas usando integrações de clientes do Kafka, como serializadores ou desserializadores, geralmente você usa o nome do assunto em vez do caminho completo do recurso.
Estratégias de nomenclatura de assunto
Ao trabalhar com o registro de esquema, especialmente com integrações de clientes do Kafka, como serializadores e desserializadores, o nome do assunto é crucial. A estratégia de nomenclatura do assunto 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.
Para configurar a estratégia de nomenclatura do assunto, defina 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 produtores 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 mensagens:
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 estã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 seguir uma lista de desvantagens de usar TopicNameStrategy:
- Cada tópico pode processar apenas 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 do Protobuf:
com.example.data.Order - Assunto do esquema
customer:com.example.data.Customer - Assunto do 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 o 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 seguir uma 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 diferentes versões 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:
Assunto:
user-eventsNome totalmente qualificado:
com.example.events.PageViewNome do assunto para esta combinação:
user-events-com.example.events.PageViewOutro tema:
product-interactionsNome totalmente qualificado:
com.example.events.PageViewNome do assunto para esta combinação:
product-interactions-com.example.events.PageView
Confira a lista de vantagens de usar TopicRecordNameStrategy:
Assim como
RecordNameStrategy, você pode enviar diferentes tipos de registros para o mesmo tópico.Ao contrário de
RecordNameStrategy, essa estratégia permite evoluir 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 seguir uma lista de desvantagens de usar TopicRecordNameStrategy:
- Os nomes de assunto podem ficar bastante longos devido à combinação do nome do tópico e do nome de registro totalmente qualificado.