Une ressource Google Cloud est un composant que vous créez ou utilisez dans Google Cloud. Ces ressources constituent les éléments de base de vos applications et systèmes exécutés sur la plate-forme.
Voici les ressources de Managed Service pour Apache Kafka :
Cluster
Sujet
Groupe de consommateurs
LCA
Registre de schémas
Contexte (dans un registre de schémas)
Sujet (dans un registre de schémas ou un contexte)
Version (versions d'un schéma sous un sujet)
Schéma (identifié par un ID, associé à un ou plusieurs sujets et versions)
Pour en savoir plus sur l'attribution de noms aux ressources Google Cloud en général, consultez Noms de ressources. L'API du 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 habituelles.
Format de nommage des ressources
Voici les formats des différentes ressources :
Cluster :
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}Thème :
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}ACL :
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 l'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 sujet) :
- 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 :
Les sections suivantes présentent chaque composant.
ID du projet
La valeur doit correspondre à l'ID ou au numéro du projet, disponibles dans la console Google Cloud . 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 Managed Service pour Apache Kafka compatibles. 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
goog;Commencer par une lettre
Contraintes de longueur :
Les ID de cluster doivent comporter entre 3 et 255 caractères.
ID de sujet et de groupe de consommateurs : toute longueur autorisée par Apache Kafka. Les noms de sujets Apache Kafka sont limités à 249 caractères.
ID du registre de schémas : contient jusqu'à 255 caractères.
ID du contexte : contient jusqu'à 255 caractères.
ID du sujet : contient jusqu'à 255 octets UTF-8.
Contraintes concernant les caractères :
ID de cluster : doit correspondre à l'expression régulière
^[a-z]([-a-z0-9]*[a-z0-9])?. Cela signifie que vous pouvez utiliser des lettres minuscules, des chiffres et des traits d'union. Il doit commencer par une lettre et ne peut pas se terminer par un trait d'union.ID de sujet et de groupe de consommateurs : la validation est effectuée 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 (-).
ID du registre de schémas : lettres (majuscules ou minuscules), chiffres et traits de soulignement
_.ID du contexte : lettres (majuscules ou minuscules), chiffres et les caractères spéciaux suivants : tirets
-, points., traits de soulignement_, tildes~, pourcentages%ou signes plus+.ID du sujet : lettres (majuscules ou minuscules), chiffres et les caractères spéciaux suivants : tirets
-, points., traits de soulignement_, tildes~, pourcentages%ou signes plus+.
ID de la LCA
acl_id définit le modèle de ressource auquel s'appliquent les entrées ACL. Toutes les entrées de la LCA s'appliquent au modèle de ressource encodé dans l'ID de la LCA.
acl_id doit être structuré comme suit :
Pour les LCA sur le cluster :
cluster
Pour les LCA sur une seule ressource du cluster :
topic/{RESOURCE_NAME}consumerGroup/{RESOURCE_NAME}transactionalId/{RESOURCE_NAME}
Pour les LCA sur toutes les ressources correspondant à un préfixe :
topicPrefixed/{RESOURCE_NAME}consumerGroupPrefixed/{RESOURCE_NAME}transactionalIdPrefixed/{RESOURCE_NAME}
Pour les LCA sur toutes les ressources d'un type donné (caractère générique) :
allTopics(représentetopic/*)allConsumerGroups(représenteconsumerGroup/*)allTransactionalIds(représentetransactionalId/*)
{RESOURCE_NAME} : nom de la ressource spécifique.
Exemples :
- Pour accorder des autorisations sur un thème spécifique
my-topic:topic/my-topic - Pour accorder des autorisations sur tous les thèmes commençant par
test-:topicPrefixed/test- - Pour accorder des autorisations sur le cluster lui-même :
cluster - Pour accorder des autorisations sur un groupe :
allConsumerGroups - Pour accorder des autorisations sur un ID de transaction spécifique
tx-id:transactionalId/tx-id
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 tous les autres caractères spéciaux sont correctement encodés ou décodés lorsqu'ils sont utilisés pour 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. En revanche, 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 faites référence à un sujet des bibliothèques clientes Kafka, le chemin d'accès complet à la ressource n'est pas utilisé. Seul le nom du thème est utilisé. De même, lorsque vous interagissez avec des schémas à l'aide d'intégrations de clients Kafka comme les sérialiseurs ou les désérialiseurs, vous utilisez généralement le nom du sujet plutôt que le chemin d'accès complet à la ressource.
Stratégies de dénomination des sujets
Lorsque vous utilisez un registre de schémas, en particulier avec des intégrations de clients Kafka comme les sérialiseurs et les désérialiseurs, le nom du sujet est essentiel. La stratégie de dénomination des sujets détermine la manière dont un schéma est enregistré et récupéré à partir du registre de schémas. Différentes stratégies offrent des niveaux de flexibilité et de contrôle variables sur l'évolution du schéma.
Vous pouvez configurer la stratégie de dénomination des sujets 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 du sujet est directement dérivé 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 des valeurs de message :
orders-value - Objet des clés de message :
orders-key
Voici une liste des avantages liés à l'utilisation de TopicNameStrategy :
Il s'agit d'une stratégie simple qui convient à de nombreux cas d'utilisation.
Les schémas sont directement associés à un sujet, ce qui vous permet de faire évoluer les types d'enregistrements d'un même sujet de manière indépendante.
Voici une liste des inconvénients liés à l'utilisation de TopicNameStrategy :
- Chaque thème ne peut gérer qu'un seul type de message basé sur le schéma de valeur. En effet, le nom du sujet est fixe et correspond au nom de la rubrique. Si vous devez envoyer différents types d'enregistrements au même thème, 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 sujet.
Voici quelques exemples :
- Nom du schéma Avro :
com.example.data.Customer - Nom du message Protobuf :
com.example.data.Order - Objet du schéma
customer:com.example.data.Customer - Objet du schéma
order:com.example.data.Order
Voici une liste des avantages liés à l'utilisation de RecordNameStrategy :
Étant donné que le nom du sujet n'est pas lié au sujet, vous pouvez envoyer différents types d'enregistrements au même sujet Kafka. Cela est possible à condition que chaque type d'enregistrement possède son propre nom complet unique et le schéma correspondant 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 sujet.
Voici une liste des inconvénients liés à l'utilisation de RecordNameStrategy :
- Vous devez utiliser le même sujet et la même version pour tous les thèmes 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 thèmes.
TopicRecordNameStrategy
Cette stratégie combine des aspects de TopicNameStrategy et de RecordNameStrategy.
Le nom du sujet est une combinaison du nom du sujet Kafka et du nom complet de la classe de l'enregistrement, au format TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.
Voici quelques exemples :
Thème :
user-eventsNom complet :
com.example.events.PageViewNom du sujet pour cette combinaison :
user-events-com.example.events.PageViewAutre thème :
product-interactionsNom complet :
com.example.events.PageViewNom du sujet pour cette combinaison :
product-interactions-com.example.events.PageView
Voici une liste des avantages liés à 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 liés à l'utilisation de TopicRecordNameStrategy :
- Les noms de sujet peuvent devenir assez longs en raison de la combinaison du nom du thème et du nom complet de l'enregistrement.