Une Google Cloud ressource est un composant que vous créez ou utilisez dans le Google Cloud. Ces ressources constituent les blocs de construction de vos applications et systèmes exécutés sur la plate-forme.
Les ressources de Managed Service pour Apache Kafka incluent les éléments suivants :
Cluster
Sujet
Groupe de consommateurs
ACL
Registre de schémas
Contexte (dans un registre de schémas)
Objet (dans un registre de schémas ou un contexte)
Version (versions d'un schéma sous un objet)
Schéma (identifié par un ID, associé à un ou plusieurs objets et versions)
Pour en savoir plus sur la dénomination des ressources générales Google Cloud , consultez Noms de ressources. L'API de registre de schémas pour Managed Service pour Apache Kafka a été conçue pour être compatible avec une API Open Source existante. Par conséquent, certaines conventions de dénomination peuvent différer des normes d'API classiques.
Format de dénomination des ressources
Voici les formats des différentes ressources :
Cluster:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}Sujet :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}Groupe de consommateurs :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}LCA :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}Registre de schémas :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}Contexte :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}Objet :
- Dans le contexte par défaut :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID} - Dans un contexte spécifique :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}
- Dans le contexte par défaut :
Schéma (identifié par un ID) :
- Dans le contexte par défaut :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID} - Dans un contexte spécifique :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}
- Dans le contexte par défaut :
Version (identifiée par un numéro de version sous un objet) :
- Dans le contexte par défaut :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID} - Dans un contexte spécifique :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
- Dans le contexte par défaut :
Chaque composant est décrit dans les sections suivantes.
ID du projet
La valeur doit correspondre à l'ID du projet ou au numéro du projet, disponible dans
la Google Cloud console. Par exemple, my-cool-project est un ID de projet, tandis que 123456789123 est un numéro de projet.
Emplacement
La valeur doit correspondre à l'un des emplacements compatibles avec Managed Service pour Apache Kafka. Pour obtenir la liste des emplacements disponibles, consultez Emplacements Managed Service pour Apache Kafka.
ID
ID est le dernier segment du chemin d'accès à la ressource. Les variables telles que
{CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID},
{SCHEMA_REGISTRY_ID}, {CONTEXT_ID} et
{SUBJECT_ID} doivent respecter les consignes suivantes :
Ne pas commencer par la chaîne
googCommencer par une lettre
Contraintes de longueur :
Les ID de cluster doivent contenir entre 3 et 255 caractères.
Les ID de sujet et de groupe de consommateurs peuvent avoir n'importe quelle longueur autorisée par Apache Kafka. Les noms de sujet Apache Kafka sont limités à 249 caractères.
L'ID de registre de schémas peut contenir jusqu'à 255 caractères.
L'ID de contexte peut contenir jusqu'à 255 caractères.
L'ID d'objet peut contenir jusqu'à 255 octets UTF-8.
Contraintes de caractères :
Les ID de cluster doivent correspondre à l'expression régulière
^[a-z]([-a-z0-9]*[a-z0-9])?. Cela signifie qu'ils doivent contenir des lettres minuscules, des chiffres et des traits d'union. Ils doivent commencer par une lettre et ne peuvent pas se terminer par un trait d'union.Les ID de sujet et de groupe de consommateurs sont validés par Kafka. Les caractères autorisés sont `[a-zA-Z0-9.-]`, qui incluent les caractères alphanumériques ASCII, les points (.), les traits de soulignement () et les tirets (-).
L'ID de registre de schémas doit contenir des lettres (majuscules ou minuscules), des chiffres et des traits de soulignement
_.L'ID de contexte doit contenir des lettres (majuscules ou minuscules), des chiffres et les caractères spéciaux suivants : tirets
-, points., traits de soulignement_, tildes~, pourcentages%ou signes plus+.L'ID d'objet doit contenir des lettres (majuscules ou minuscules), des chiffres et les caractères spéciaux suivants : tirets
-, points., traits de soulignement_, tildes~, pourcentages%ou signes plus+.
Caractères spéciaux
Vous pouvez utiliser les caractères spéciaux listés dans la section précédente dans les ID de ressources sans codage d'URL. Toutefois, vous devez vous assurer que tout autre caractère spécial est correctement encodé ou décodé lorsqu'il est utilisé dans des URL.
Par exemple, mi-tópico est un ID non valide si ó n'est pas un caractère autorisé
pour ce type d'ID de ressource spécifique. Toutefois, mi-topico serait valide si seules les lettres latines de base étaient autorisées. Ce format est important lorsque vous effectuez des appels REST.
Si vous référencez un sujet à partir des bibliothèques clientes Kafka, le chemin d'accès complet à la ressource n'est pas utilisé. Seul le nom du sujet est utilisé. De même, lorsque vous interagissez avec des schémas à l'aide d'intégrations de clients Kafka, comme des sérialiseurs ou des désérialiseurs, vous utilisez généralement le nom de l'objet plutôt que le chemin d'accès complet à la ressource.
Stratégies de dénomination des objets
Lorsque vous utilisez un registre de schémas, en particulier avec des intégrations de clients Kafka comme des sérialiseurs et des désérialiseurs, le nom de l'objet est essentiel. La stratégie de dénomination des objets détermine comment un schéma est enregistré et récupéré à partir du registre de schémas. Différentes stratégies offrent différents niveaux de flexibilité et de contrôle sur l'évolution des schémas.
Vous pouvez configurer la stratégie de dénomination des objets en définissant la propriété key.subject.name.strategy ou value.subject.name.strategy dans la configuration de votre client Kafka.
TopicNameStrategy
Il s'agit de la stratégie par défaut pour les bibliothèques clientes Kafka Open Source.
Le nom de l'objet est dérivé directement du nom du sujet Kafka, auquel est ajouté key pour les clés de message ou value pour les valeurs de message. Si auto.register.schema
est défini sur true, les clients producteurs utilisent topicName-value ou topicName-key
pour un sujet nommé topicName.
Voici quelques exemples :
- Nom du sujet :
orders - Objet pour les valeurs de message :
orders-value - Objet pour les clés de message :
orders-key
Voici une liste des avantages de l'utilisation de TopicNameStrategy :
Il s'agit d'une stratégie simple, ce qui la rend adaptée à de nombreux cas d'utilisation.
Les schémas sont directement liés à un sujet, ce qui vous permet de faire évoluer les types d'enregistrements dans un seul sujet de manière indépendante.
Voici une liste des inconvénients de l'utilisation de TopicNameStrategy :
- Chaque sujet ne peut gérer qu'un seul type de message basé sur le schéma de valeur. En effet, le nom de l'objet est fixe par rapport au nom du sujet. Si vous devez envoyer différents types d'enregistrements au même sujet, cette stratégie ne fonctionnera pas.
RecordNameStrategy
Cette stratégie utilise le nom de classe complet de l'enregistrement Avro ou Protobuf comme nom de l'objet.
Voici quelques exemples :
- Nom du schéma Avro :
com.example.data.Customer - Nom du message Protobuf :
com.example.data.Order - Objet pour le schéma
customer:com.example.data.Customer - Objet pour le schéma
order:com.example.data.Order
Voici une liste des avantages de l'utilisation de RecordNameStrategy :
Étant donné que le nom de l'objet n'est pas lié au sujet, vous pouvez envoyer différents types d'enregistrements au même sujet Kafka. Cela est possible tant que chaque type d'enregistrement possède son propre nom complet unique et que le schéma correspondant est enregistré.
Un schéma pour un type d'enregistrement spécifique tel que
com.example.common.Addresspeut être utilisé dans plusieurs sujets, et son évolution est gérée de manière centralisée sous un seul objet.
Voici une liste des inconvénients de l'utilisation de RecordNameStrategy :
- Vous devez utiliser le même objet et la même version pour tous les sujets qui utilisent un type d'enregistrement particulier. Cela peut être restrictif si vous avez besoin de différentes versions du même type d'enregistrement dans différents sujets.
TopicRecordNameStrategy
Cette stratégie combine des aspects de TopicNameStrategy et de RecordNameStrategy.
Le nom de l'objet est une combinaison du nom du sujet Kafka et du nom de classe complet de l'enregistrement, au format TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.
Voici quelques exemples :
Sujet :
user-eventsNom complet :
com.example.events.PageViewNom de l'objet pour cette combinaison :
user-events-com.example.events.PageViewAutre sujet :
product-interactionsNom complet :
com.example.events.PageViewNom de l'objet pour cette combinaison :
product-interactions-com.example.events.PageView
Voici une liste des avantages de l'utilisation de TopicRecordNameStrategy :
Comme pour
RecordNameStrategy, vous pouvez envoyer différents types d'enregistrements au même sujet.Contrairement à
RecordNameStrategy, cette stratégie vous permet de faire évoluer le schéma d'un type d'enregistrement spécifique de manière indépendante dans chaque sujet. Cela signifie quemy-topic-com.example.project.MyRecordpeut évoluer différemment deanother-topic-com.example.project.MyRecord.
Voici une liste des inconvénients de l'utilisation de TopicRecordNameStrategy :
- Les noms d'objets peuvent devenir assez longs en raison de la combinaison du nom du sujet et du nom complet de l'enregistrement.