Una risorsa Google Cloud è qualsiasi componente che crei o utilizzi all'interno di Google Cloud. Queste risorse costituiscono i componenti di base delle tue applicazioni e dei tuoi sistemi in esecuzione sulla piattaforma.
Le risorse in Managed Service per Apache Kafka includono quanto segue:
Cluster
Argomento
Gruppo di consumer
ACL
Registro di schema
Contesto (all'interno di un registro di schema)
Soggetto (all'interno di un registro di schema o contesto)
Versione (versioni di uno schema in un soggetto)
Schema (identificato dall'ID, associato a uno o più argomenti e versioni)
Per saperne di più sulla denominazione delle risorse Google Cloud generali, consulta Nomi delle risorse. L'API Schema Registry per Managed Service per Apache Kafka è stata progettata per essere compatibile con un'API open source esistente, pertanto alcune convenzioni di denominazione potrebbero differire dagli standard API tipici.
Formato di denominazione delle risorse
Ecco i formati per le diverse risorse:
Cluster:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}Argomento:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}Gruppo di consumatori:
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 di schema:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}Contesto:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}Oggetto:
- Nel contesto predefinito:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID} - In un contesto specifico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}
- Nel contesto predefinito:
Schema (identificato dall'ID):
- Nel contesto predefinito:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID} - In un contesto specifico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}
- Nel contesto predefinito:
Versione (identificata dal numero di versione sotto un argomento):
- Nel contesto predefinito:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID} - In un contesto specifico:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
- Nel contesto predefinito:
Nelle sezioni successive viene fornita un'analisi dettagliata di ogni componente.
ID progetto
Il valore deve essere l'ID progetto o il numero del progetto, disponibile nella console Google Cloud . Ad esempio, my-cool-project è un ID progetto,
mentre 123456789123 è un numero di progetto.
Località
Il valore deve essere una delle località di Managed Service per Apache Kafka supportate. Per un elenco di località disponibili, consulta le località di Managed Service per Apache Kafka.
ID
ID è l'ultimo segmento del percorso della risorsa. Le variabili come
{CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID},
{SCHEMA_REGISTRY_ID}, {CONTEXT_ID} e
{SUBJECT_ID} devono essere conformi alle seguenti linee guida:
Non iniziare con la stringa
googInizia con una lettera
Vincoli di lunghezza:
ID cluster: contengono da 3 a 53 caratteri.
ID argomento, gruppo di consumatori: qualsiasi lunghezza consentita da Apache Kafka. I nomi degli argomenti Apache Kafka non possono superare 249 caratteri.
ID registro schema: contiene fino a 255 caratteri.
ID contesto: contiene fino a 255 caratteri.
ID soggetto: contiene fino a 255 byte UTF-8.
Vincoli dei caratteri:
ID cluster: devono corrispondere all'espressione regolare
^[a-z]([-a-z0-9]*[a-z0-9])?. Ciò significa lettere minuscole, numeri e trattini. Deve iniziare con una lettera e non può terminare con un trattino.ID argomento e gruppo di consumer: la convalida viene eseguita da Kafka. I caratteri consentiti sono `[a-zA-Z0-9.-], che includono caratteri alfanumerici ASCII, punti (.), trattini bassi () e trattini (-).
ID registro schema: lettere (maiuscole o minuscole), numeri e trattini bassi
_.ID contesto: lettere (maiuscole o minuscole), numeri e i seguenti caratteri speciali: trattini
-, punti., trattini bassi_, tildi~, percentuali%o segni più+.ID soggetto: lettere (maiuscole o minuscole), numeri e i seguenti caratteri speciali: trattini
-, punti., trattini bassi_, tildi~, percentuali%o segni più+.
Caratteri speciali
Puoi utilizzare i caratteri speciali elencati nella sezione precedente negli ID risorsa senza codifica URL. Tuttavia, devi assicurarti che qualsiasi altro carattere speciale sia codificato o decodificato correttamente quando viene utilizzato negli URL.
Ad esempio, mi-tópico è un ID non valido se ó non è un carattere consentito
per quel tipo specifico di ID risorsa. Tuttavia, mi-topico sarebbe valido se
fossero consentite solo lettere latine di base. Questo formato è importante quando
effettui chiamate REST.
Se fai riferimento a un argomento dalle librerie client Kafka, il percorso completo della risorsa non viene utilizzato. Viene utilizzato solo il nome dell'argomento. Allo stesso modo, quando interagisci con gli schemi utilizzando integrazioni client Kafka come serializzatori o deserializzatori, in genere utilizzi il nome del soggetto anziché il percorso completo della risorsa.
Strategie di denominazione dei soggetti
Quando lavori con il registro di schema, in particolare con le integrazioni del client Kafka come i serializzatori e i deserializzatori, il nome del soggetto è fondamentale. La strategia di denominazione dell'argomento determina la modalità di registrazione e recupero di uno schema dal registro di schema. Le diverse strategie offrono vari livelli di flessibilità e controllo sull'evoluzione dello schema.
Puoi configurare la strategia di denominazione dei soggetti impostando la proprietà
key.subject.name.strategy o value.subject.name.strategy nella configurazione del client Kafka.
TopicNameStrategy
Questa è la strategia predefinita per le librerie client Kafka open source.
Il nome del soggetto deriva direttamente dal nome dell'argomento Kafka, a cui vengono aggiunti
key per le chiavi dei messaggi o value per i valori dei messaggi. Se auto.register.schema
è impostato su true, i client produttori utilizzano topicName-value o topicName-key
per un argomento denominato topicName.
Ecco alcuni esempi:
- Nome argomento:
orders - Oggetto per i valori del messaggio:
orders-value - Oggetto per le chiavi dei messaggi:
orders-key
Di seguito è riportato un elenco dei vantaggi dell'utilizzo di TopicNameStrategy:
Si tratta di una strategia semplice, adatta a molti casi d'uso.
Gli schemi sono collegati direttamente a un argomento, il che ti consente di far evolvere i tipi di record all'interno di un singolo argomento in modo indipendente.
Di seguito è riportato un elenco di svantaggi dell'utilizzo di TopicNameStrategy:
- Ogni argomento può gestire in modo efficace un solo tipo di messaggio in base allo schema dei valori. Questo perché il nome del soggetto è fisso rispetto al nome dell'argomento. Se devi inviare diversi tipi di record allo stesso argomento, questa strategia non funzionerà.
RecordNameStrategy
Questa strategia utilizza il nome di classe completo del record Avro o Protobuf come nome del soggetto.
Ecco alcuni esempi:
- Nome schema Avro:
com.example.data.Customer - Nome del messaggio Protobuf:
com.example.data.Order - Oggetto per lo schema
customer:com.example.data.Customer - Oggetto per lo schema
order:com.example.data.Order
Di seguito è riportato un elenco dei vantaggi dell'utilizzo di RecordNameStrategy:
Poiché il nome del soggetto non è collegato all'argomento, puoi inviare diversi tipi di record allo stesso argomento Kafka. Ciò è possibile a condizione che ogni tipo di record abbia il proprio nome completo univoco e lo schema corrispondente registrato.
Uno schema per un tipo di record specifico, ad esempio
com.example.common.Address, può essere utilizzato in più argomenti e la sua evoluzione viene gestita centralmente in un unico argomento.
Di seguito è riportato un elenco di svantaggi dell'utilizzo di RecordNameStrategy:
- Devi utilizzare lo stesso argomento e la stessa versione per tutti gli argomenti che utilizzano un particolare tipo di record. Questo può essere restrittivo se hai bisogno di versioni diverse dello stesso tipo di record in argomenti diversi.
TopicRecordNameStrategy
Questa strategia combina aspetti di TopicNameStrategy e RecordNameStrategy.
Il nome del soggetto è una combinazione del nome dell'argomento Kafka e del nome
della classe completamente qualificato del record, formattato come
TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.
Ecco alcuni esempi:
Argomento:
user-eventsNome completo:
com.example.events.PageViewNome del soggetto per questa combinazione:
user-events-com.example.events.PageViewUn altro argomento:
product-interactionsNome completo:
com.example.events.PageViewNome del soggetto per questa combinazione:
product-interactions-com.example.events.PageView
Di seguito è riportato un elenco dei vantaggi dell'utilizzo di TopicRecordNameStrategy:
Come per
RecordNameStrategy, puoi inviare diversi tipi di record allo stesso argomento.A differenza di
RecordNameStrategy, questa strategia ti consente di evolvere lo schema per un tipo di record specifico in modo indipendente all'interno di ogni argomento. Ciò significa chemy-topic-com.example.project.MyRecordpuò evolversi in modo diverso daanother-topic-com.example.project.MyRecord.
Di seguito è riportato un elenco di svantaggi dell'utilizzo di TopicRecordNameStrategy:
- I nomi dei soggetti possono diventare piuttosto lunghi a causa della combinazione del nome dell'argomento e del nome completo del record.