Créer un sujet

Ce document explique comment créer un sujet dans un registre de schémas. Un sujet est un conteneur logique pour différentes versions d'un schéma. Lorsque vous créez un sujet pour la première fois, vous créez également la première version du schéma pour ce sujet.

Vous pouvez créer un sujet de l'une des manières suivantes :

Implicite (par défaut) : le comportement par défaut de nombreux clients producteurs et consommateurs consiste à créer automatiquement un schéma qui n'existe pas lorsque le client se connecte. Le sujet et la version faisant référence au schéma sont également créés automatiquement. Cette approche est pratique, mais peut entraîner des incohérences potentielles dans les données si plusieurs clients créent des versions simultanément.
Explicite (recommandé) : dans cette méthode, chaque schéma doit être créé dans le registre avant qu'un client producteur ou consommateur puisse l'utiliser. Pour ce faire, vous pouvez utiliser la console Google Cloud ou l'API Managed Kafka.

Ce comportement doit être configuré dans les paramètres de votre client. Pour en savoir plus, consultez la documentation de votre bibliothèque cliente de sérialiseur ou désérialiseur.

Avant de commencer

En savoir plus sur la présentation du schéma
Créez un registre de schémas si vous n'en avez pas encore.
Comprendre les références de schéma.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un sujet, demandez à votre administrateur de vous accorder le rôle IAM Éditeur du registre de schémas Kafka géré (roles/managedkafka.schemaRegistryEditor) sur votre projet ou registre de schémas. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer un sujet. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un sujet :

Accordez cette autorisation dans le contexte parent ou le contexte par défaut : managedkafka.versions.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Le rôle de niveau supérieur Administrateur du registre de schémas Managed Kafka (roles/managedkafka.schemaRegistryAdmin) inclut également les autorisations permettant de créer et de gérer les versions de sujets.

Pour en savoir plus sur les rôles prédéfinis disponibles pour Managed Service pour Apache Kafka, consultez la documentation sur le contrôle des accès.

Créer un sujet ou une première version d'un schéma

Lorsque vous créez un sujet, vous créez également sa première version. Cette première version crée un schéma ou fait référence à un schéma existant.

Console

Dans la console Google Cloud , accédez à la page Registres de schémas.

Accéder aux registres de schémas
Cliquez sur le nom du registre de schémas dans lequel vous souhaitez créer un sujet.
Cliquez sur Créer un sujet.
Dans le champ Nom du sujet, saisissez un nom unique pour votre sujet.

Le nom doit commencer par une lettre et ne contenir que des lettres, des chiffres et les caractères spéciaux suivants : tiret (-), point (.), trait de soulignement (_), tilde (~), signe de pourcentage (%) ou signe plus (+). Le nom d'un sujet est immuable.

Pour en savoir plus sur le choix d'un nom de sujet, consultez Stratégies de dénomination des sujets.
Pour Contexte, choisissez un contexte ou créez-en un. Les contextes agissent comme des espaces de noms pour organiser vos sujets et vos schémas, en assurant l'isolation entre différents groupes.
- Pour utiliser un contexte existant, sélectionnez-le dans la liste Contexte. Le contexte par défaut s'affiche sous la forme (default context).
- Pour créer un contexte, procédez comme suit :
  1. Sélectionnez Créer un contexte dans la liste Contexte.
  2. Dans le champ Nom du contexte, saisissez un nom pour le contexte.
    
    Le nom doit commencer par une lettre et ne peut contenir que des lettres, des chiffres et les caractères spéciaux suivants : tiret (-), point (.), trait de soulignement (_), tilde (~), signe de pourcentage (%) ou signe plus (+). Le nom d'un contexte est immuable.
  3. Cliquez sur Enregistrer.
Pour Type de schéma, sélectionnez Avro ou Tampon de protocole.
Dans le champ Définition de schéma, saisissez la définition du schéma. Le format du schéma doit correspondre au type de schéma. N'incluez pas d'informations sensibles telles que des informations permettant d'identifier personnellement l'utilisateur ou des données de sécurité dans les noms des champs de votre schéma.
Si votre schéma utilise ou dépend de structures de données définies dans d'autres schémas du registre de schémas, procédez comme suit :
1. Cliquez sur Ajouter une référence de schéma.
2. Dans le champ Nom de référence, saisissez le nom de référence du schéma référencé.
3. Dans la liste Sujet, sélectionnez le sujet contenant le schéma référencé.
4. Dans la liste Version, sélectionnez le numéro de version du schéma référencé.
5. Cliquez sur OK.
Répétez ces étapes pour chaque schéma référencé.
Cliquez sur Créer.

REST

La demande doit être authentifiée à l'aide d'un jeton d'accès dans l'en-tête Authorization. Pour obtenir un jeton d'accès pour les identifiants par défaut actuels de l'application, exécutez la commande suivante : gcloud auth application-default print-access-token.

Les exemples d'API REST suivants créent la première version d'un sujet.

Pour créer un sujet dans le contexte par défaut, envoyez une requête POST à l'URI spécifié à l'aide de la méthode projects.locations.schemaRegistries.subjects.versions.create :

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Si vous utilisez un contexte spécifique, vous pouvez également l'inclure dans l'URI de la collection d'objets à l'aide de la méthode projects.locations.schemaRegistries.contexts.subjects.versions.create :

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Remplacez les éléments suivants :

PROJECT_ID (obligatoire) : ID de votre projet Google Cloud.
LOCATION (obligatoire) : Google Cloud région dans laquelle se trouve le registre de schémas.
REGISTRY_ID (obligatoire) : ID du registre de schéma cible.
CONTEXT_ID (facultatif) : ID du contexte contenant le sujet. Utilisez . pour le contexte par défaut si vous souhaitez être explicite, sinon omettez /contexts/CONTEXT_ID pour utiliser le contexte par défaut de manière implicite.

Le nom doit commencer par une lettre et ne peut contenir que des lettres, des chiffres et les caractères spéciaux suivants : tirets -, points ., traits de soulignement _, tildes ~, signes de pourcentage % ou signes plus +. Le nom d'un contexte est immuable.
SUBJECT_ID (obligatoire) : ID du nouveau sujet sous lequel créer la première version.

Le nom doit commencer par une lettre et ne peut contenir que des lettres, des chiffres et les caractères spéciaux suivants : tirets -, points ., traits de soulignement _, tildes ~, signes de pourcentage % ou signes plus +. Le nom d'un sujet est immuable.

Corps de la requête :

Incluez un objet JSON dans le corps de la requête, en spécifiant les détails du schéma :

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Remplacez les éléments suivants :

YOUR_SCHEMA_DEFINITION_STRING (obligatoire) : chaîne contenant la charge utile de la définition du schéma.

N'incluez pas d'informations sensibles telles que des informations permettant d'identifier personnellement l'utilisateur ou des données de sécurité dans les noms des champs de votre schéma.
schemaType (facultatif) : type de schéma. Il peut s'agir de AVRO ou PROTOBUF. La valeur par défaut est AVRO si elle est omise.
references (facultatif) : tableau d'objets définissant les schémas référencés par ce schéma.
- REFERENCE_NAME : nom utilisé pour faire référence à l'autre schéma dans la définition de ce schéma.
- REFERENCED_SUBJECT_ID : ID du sujet du schéma référencé.
- REFERENCED_VERSION_NUMBER : numéro de version spécifique du schéma du sujet référencé.
versionId, schemaId : champs facultatifs généralement gérés par le service. Pour la première version d'un sujet, versionId sera défini sur "1".

Si la requête aboutit, que le schéma est valide et qu'il passe les vérifications de compatibilité (si elles sont configurées), l'API renvoie un code d'état 200 OK. Le corps de la réponse contient l'ID de schéma utilisé par la version créée, qui est différent de l'ID de version.

Pour en savoir plus, consultez la documentation sur l'API REST.

Étapes suivantes

Apache Kafka® est une marque déposée d'Apache Software Foundation ou de ses filiales aux États-Unis et/ou dans d'autres pays.