Enregistrer une nouvelle version du schéma

Une fois que vous avez créé un sujet, vous pouvez y ajouter de nouvelles versions. Ce processus est appelé "enregistrement d'une nouvelle version de schéma". Chaque nouvelle version représente une évolution du schéma associé à ce sujet.

Un sujet peut avoir plusieurs versions. Les versions d'un sujet suivent des règles de compatibilité configurables pour assurer une évolution sécurisée des schémas. Par exemple, un sujet peut exiger que toutes les modifications soient rétrocompatibles. L'ajout d'un champ facultatif est un exemple de modification rétrocompatible. L'ajout d'un champ obligatoire est considéré comme une modification non rétrocompatible. Si votre sujet est configuré pour la rétrocompatibilité, cette modification n'est pas autorisée. Toutefois, si votre sujet est configuré pour la compatibilité ascendante, vous pouvez ajouter un champ obligatoire.

Les vérifications de compatibilité ne sont pas rétroactives. Si les règles de compatibilité sont modifiées pour un registre de sujet ou de schéma, les versions déjà existantes dans le sujet ne sont pas revalidées par rapport aux nouvelles règles. Pour en savoir plus sur la compatibilité, consultez À propos du type de compatibilité.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour enregistrer une version de schéma pour un sujet, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Managed Kafka Schema Registry (roles/managedkafka.schemaRegistryEditor) sur votre projet ou sur le registre de schémas et le sujet spécifiques. 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 enregistrer une version de schéma pour un sujet. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour enregistrer une version de schéma pour 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 ces autorisations.

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.

Enregistrer une nouvelle version du schéma

Pour enregistrer une nouvelle version de schéma, procédez comme suit.

Console

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

    Accéder aux registres de schémas

  2. Cliquez sur le nom du registre de schémas dans lequel vous souhaitez enregistrer une nouvelle version de schéma.

  3. Sous Sujets dans ce registre de schémas, cliquez sur le nom du sujet.

  4. Sur la page Détails du sujet, cliquez sur Créer une version.

  5. Le champ Définition du schéma affiche la définition de la dernière version. Mettez à jour la définition dans ce champ pour la nouvelle version. 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.

  6. 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é.

  7. Facultatif : Pour vérifier si le nouveau schéma est compatible avec la version précédente, cliquez sur Vérifier la compatibilité.

    Si le schéma est compatible, une coche  s'affiche. Sinon, un message d'erreur s'affiche. Dans ce cas, corrigez l'erreur et cliquez de nouveau sur Vérifier la compatibilité.

    La vérification de la compatibilité effectuée dépend du type de compatibilité du sujet.

  8. Cliquez sur Créer. Si la définition du schéma est valide et réussit les vérifications de compatibilité du sujet, la nouvelle version s'affiche sous Toutes les versions.

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.

Pour enregistrer une nouvelle version de schéma pour un sujet dans le contexte par défaut, envoyez une requête POST à l'URI spécifique à l'aide de la méthode projects.locations.schemaRegistries.subjects.versions.create :

POST https://managedkafka.googleapis.com/v1/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

Vous pouvez également inclure le contexte dans l'URI de la collection de versions et utiliser la méthode projects.locations.schemaRegistries.contexts.subjects.versions.create si vous utilisez un contexte spécifique.

POST https://managedkafka.googleapis.com/v1/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 . (un seul point) 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.
  • SUBJECT_ID (obligatoire) : ID du sujet sous lequel créer la nouvelle version.

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" | "JSON", // 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.

  • schemaType (facultatif, dans l'objet schema) : 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, dans l'objet schema) : 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 : nom complet de l'objet du schéma référencé. Exemple : projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject

    • REFERENCED_VERSION_NUMBER : numéro de version spécifique (entier) du schéma du sujet référencé.

  • versionId, schemaId : champs facultatifs généralement gérés par le service. Lors de l'enregistrement de la version du schéma, le service attribue le prochain numéro de version disponible.

Si la requête aboutit, l'API renvoie un code d'état 200 OK et un corps de réponse contenant l'ID du schéma.

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.