Créer et gérer des schémas protobuf

Ce document explique comment créer des bundles de schémas et effectuer des opérations sur ceux-ci.

Dans Bigtable, vous pouvez utiliser des schémas de tampon de protocole (protobuf) pour interroger des champs individuels dans des messages protobuf stockés sous forme d'octets dans vos colonnes. Pour ce faire, vous devez importer vos schémas dans un bundle de schémas, une ressource au niveau de la table qui contient un ou plusieurs de vos schémas protobuf.

L'utilisation de bundles de schémas offre les avantages suivants :

  • Gain de temps et d'efforts : avec les tampons de protocole, vous définissez votre structure de données une seule fois dans un fichier proto, puis vous utilisez le code source généré pour écrire et lire vos données.
  • Amélioration de la cohérence des données : en utilisant un fichier proto comme source unique de vérité, vous pouvez vous assurer que toutes les applications et tous les services utilisent le même modèle de données.
  • Élimination de la duplication des données : vous pouvez utiliser des tampons de protocole dans plusieurs projets en définissant des types de messages dans des fichiers proto qui résident en dehors de la codebase d'un projet spécifique.

Le processus d'utilisation des schémas dans Bigtable commence par vos fichiers proto. Un fichier proto est un fichier texte dans lequel vous définissez la structure de vos données. Vous utilisez l'outil de compilation protobuf, également appelé protoc, pour générer un ensemble de descripteurs de fichier protobuf, qui est un schéma lisible par machine de votre fichier proto. Vous utiliserez ensuite cet ensemble de descripteurs pour créer un bundle de schémas.

Pour obtenir des exemples de fichiers proto et de leurs ensembles de descripteurs correspondants, consultez Exemples de données.

Le diagramme suivant illustre le processus d'utilisation des schémas dans Bigtable :

Processus d'utilisation des schémas Protobuf dans Bigtable.
Figure 1. Processus d'utilisation des schémas protobuf dans Bigtable (cliquez pour agrandir).

Vous pouvez créer des bundles de schémas à l'aide de la console Google Cloud ou de Google Cloud CLI. Après avoir importé un bundle de schéma dans Bigtable, vous pouvez interroger vos données à l'aide du générateur de requêtes Bigtable Studio, de GoogleSQL pour Bigtable ou des tables externes Bigtable dans BigQuery.

Avant de commencer

Si vous prévoyez d'utiliser la gcloud CLI, procédez comme suit :

  1. Installez la Google Cloud CLI.

  2. Initialisez la gcloud CLI :

    gcloud init

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des bundles de schémas, demandez à votre administrateur de vous accorder le rôle IAM (Identity and Access Management) Administrateur Bigtable (roles/bigtable.admin) sur la table.

Ce rôle prédéfini contient les autorisations dont Bigtable a besoin pour utiliser les bundles de schémas. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

  • bigtable.schemaBundles.create
  • bigtable.schemaBundles.update
  • bigtable.schemaBundles.delete
  • bigtable.schemaBundles.get
  • bigtable.schemaBundles.list

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

Pour en savoir plus sur les rôles et les autorisations Bigtable, consultez Contrôle des accès avec IAM.

Générer un ensemble de descripteurs de fichier protobuf

Avant de pouvoir créer un bundle de schémas, vous devez générer un ensemble de descripteurs à partir de vos fichiers proto à l'aide de l'outil de compilation protobuf.

  1. Pour installer le compilateur, téléchargez le package et suivez les instructions du fichier README.

  2. Exécutez le compilateur :

    protoc --proto_path=IMPORT_PATH --include_imports \
   --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO

    Remplacez les éléments suivants :

    • IMPORT_PATH : répertoire dans lequel le compilateur protoc recherche les fichiers proto.
    • DESCRIPTOR_OUTPUT_LOCATION : répertoire dans lequel le compilateur protoc enregistre l'ensemble de descripteurs généré.
    • PATH_TO_PROTO : chemin d'accès à votre fichier proto.

Par exemple, pour créer un ensemble de descripteurs nommé library.pb pour le fichier library.proto dans le répertoire actuel, vous pouvez utiliser la commande suivante :

protoc --include_imports --descriptor_set_out=library.pb
library.proto

Créer un groupe de schémas

Console

  1. Dans la console Google Cloud , ouvrez la liste des instances Bigtable.

    Ouvrir la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le volet de navigation, cliquez sur Bigtable Studio.

  4. Dans le volet Explorateur, à côté de la table dans laquelle vous souhaitez créer un groupe de schémas, cliquez sur le menu d'actions more_vert, puis sur Créer un groupe de schémas.

  5. Dans la boîte de dialogue Créer un bundle de schémas, dans le champ ID du bundle de schémas, saisissez un identifiant unique pour le bundle de schémas.

    L'ID doit comporter entre 1 et 50 caractères, ne peut contenir que des lettres, des chiffres, des traits de soulignement et des traits d'union, ne peut pas commencer par un trait d'union et ne peut pas contenir de point (.).

  6. Dans le champ Ensemble de descripteurs de fichiers (fichier .pb), cliquez sur Parcourir pour sélectionner l'ensemble de descripteurs de fichiers protobuf que vous avez créé dans la section Générer un ensemble de descripteurs de fichiers protobuf de ce document. La taille du fichier ne peut pas dépasser 4 Mo.

  7. Cliquez sur Créer.

    Le bundle de schémas s'ouvre dans un nouvel onglet.

gcloud

Pour créer un bundle de schémas, utilisez la commande gcloud bigtable schema-bundles create :

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Remplacez les éléments suivants :

  • SCHEMA_BUNDLE_ID : identifiant unique du nouveau bundle de schémas, qui ne peut pas contenir de point (« . »).
  • INSTANCE_ID : ID de l'instance dans laquelle vous créez le bundle de schéma.
  • TABLE_ID : ID de la table dans laquelle vous créez le bundle de schéma.
  • PROTO_DESCRIPTORS_FILE : chemin d'accès à l'ensemble de descripteurs que vous avez créé dans la section Générer un ensemble de descripteurs de fichier protobuf de ce document.

Java

Pour créer un bundle de schémas, utilisez la méthode createSchemaBundle :

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la section Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

Afficher des informations sur les bundles de schémas

Avant de pouvoir afficher des informations sur les groupes de schémas, vous devez disposer d'une table Bigtable contenant au moins un groupe de schémas. Vous pouvez obtenir des informations sur les groupes de schémas d'une table en récupérant la définition d'un seul groupe de schémas ou en listant tous les groupes de schémas d'une table.

Obtenir la définition d'un groupe de schémas

Console

  1. Dans la console Google Cloud , ouvrez la liste des instances Bigtable.

    Ouvrir la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le volet de navigation, cliquez sur Bigtable Studio.

  4. Dans le volet Explorateur, développez la table contenant le bundle de schémas, puis développez Bundles de schémas.

  5. Cliquez sur le bundle de schémas que vous souhaitez afficher, ou cliquez sur le menu d'actions more_vert à côté du bundle de schémas, puis sur Afficher les détails.

    Un onglet s'ouvre et affiche la définition du bundle de schémas.

  6. Facultatif : Pour ouvrir un onglet de l'éditeur de requête SQL avec un exemple de requête qui utilise le bundle de schémas, cliquez sur le menu d'actions more_vert à côté du bundle de schémas, puis sur Exemple de requête.

gcloud

Pour obtenir des détails sur un bundle de schémas, utilisez la commande gcloud bigtable schema-bundles describe :

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Remplacez les éléments suivants :

  • SCHEMA_BUNDLE_ID : ID du bundle de schémas.
  • INSTANCE_ID : ID de l'instance
  • TABLE_ID : ID de la table.

Java

Pour obtenir la définition d'un groupe de schémas, utilisez la méthode getSchemaBundle. Cette méthode renvoie un objet SchemaBundle contenant la définition du schéma.

L'exemple suivant montre comment obtenir un bundle de schéma et désérialiser l'ensemble de descripteurs pour afficher le contenu du schéma :

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la section Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

SchemaBundle schemaBundle = null;
try {
  schemaBundle =
      adminClient.getSchemaBundle(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

Le résultat ressemble à ce qui suit :

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

Lister les bundles de schémas dans une table

Console

  1. Dans la console Google Cloud , ouvrez la liste des instances Bigtable.

    Ouvrir la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le volet de navigation, cliquez sur Bigtable Studio.

  4. Dans le volet Explorateur, développez la table contenant les bundles de schémas que vous souhaitez afficher.

  5. Développez Groupes de schémas.

    La liste des bundles de schémas de la table s'affiche. Si la table ne comporte aucun groupe de schémas, la liste Groupes de schémas ne s'affiche pas.

gcloud

Pour afficher la liste des bundles de schémas d'une table, utilisez la commande gcloud bigtable schema-bundles list :

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Remplacez les éléments suivants :

  • INSTANCE_ID : ID de l'instance
  • TABLE_ID : ID de la table.

Java

Pour afficher la liste de tous les bundles de schémas d'une table, utilisez la méthode listSchemaBundles. Cette méthode renvoie une liste d'ID de bundles de schémas.

L'exemple suivant montre comment lister les bundles de schémas d'une table :

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la section Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

List<String> schemaBundleIds = new ArrayList<>();
try {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

Le résultat ressemble à ce qui suit :

my-schema-bundle-1
my-schema-bundle-2

Mettre à jour un groupe de schémas

Lorsque vous mettez à jour un bundle de schémas, Bigtable vérifie si le nouvel ensemble de descripteurs est rétrocompatible avec l'ensemble existant. Si Bigtable détecte une incompatibilité, la mise à jour échoue avec une erreur FailedPrecondition. Nous vous recommandons de réserver les numéros de champ supprimés pour éviter qu'ils ne soient réutilisés. Pour en savoir plus, consultez Bonnes pratiques pour les protos dans la documentation protobuf.

Si vous êtes sûr que les modifications incompatibles sont sans danger et que vous souhaitez forcer une mise à jour, vous pouvez utiliser l'option --ignore-warnings avec gcloud CLI. Toutefois, vous ne pouvez pas forcer des modifications incompatibles si le bundle de schémas est utilisé par une vue matérialisée continue ou une vue logique. Les vues dépendent des définitions de message du groupe de schémas pour analyser et interroger les données. Par conséquent, des modifications incompatibles interrompraient les requêtes sur les vues logiques et entraîneraient l'échec des vues matérialisées continues lors du traitement des données. Pour apporter des modifications non rétrocompatibles à un bundle de schémas référencé par une vue, vous devez d'abord mettre à jour ou supprimer les vues de référence.

Console

  1. Dans la console Google Cloud , ouvrez la liste des instances Bigtable.

    Ouvrir la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le volet de navigation, cliquez sur Bigtable Studio.

  4. Dans le volet Explorateur, développez la table contenant le bundle de schémas, puis développez Bundles de schémas.

  5. À côté du bundle de schémas que vous souhaitez mettre à jour, cliquez sur le menu d'actions more_vert, puis sur Mettre à jour.

  6. Dans la boîte de dialogue Mettre à jour l'ensemble de schémas, dans le champ Ensemble de descripteurs de fichiers (fichier .pb), sélectionnez le nouvel ensemble de descripteurs de fichiers protobuf. La taille du fichier ne peut pas dépasser 4 Mo.

  7. Cliquez sur Enregistrer.

gcloud

Pour mettre à jour un bundle de schémas afin d'utiliser un autre ensemble de descripteurs, utilisez la commande gcloud bigtable schema-bundles update :

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Remplacez les éléments suivants :

  • SCHEMA_BUNDLE_ID : ID du bundle de schémas à mettre à jour.
  • INSTANCE_ID : ID de l'instance contenant le bundle de schémas.
  • TABLE_ID : ID de la table contenant le bundle de schémas.
  • PROTO_DESCRIPTORS_FILE : chemin d'accès au nouveau fichier d'ensemble de descripteurs.

Facultatif : pour forcer la mise à jour même s'il existe des modifications incompatibles, ajoutez l'option --ignore-warnings à la commande. Vous ne pouvez pas forcer des modifications incompatibles si le bundle de schémas est utilisé par une vue matérialisée continue ou une vue logique.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la section Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

Supprimer un groupe de schémas

Vous ne pouvez pas supprimer un groupe de schémas s'il est utilisé par une vue matérialisée continue ou une vue logique. La suppression du bundle entraînerait l'échec des requêtes sur les vues logiques et empêcherait les vues matérialisées continues de traiter les données entrantes. Pour supprimer le bundle de schémas, vous devez d'abord supprimer toutes les vues qui le référencent ou les mettre à jour pour supprimer la référence.

Console

  1. Dans la console Google Cloud , ouvrez la liste des instances Bigtable.

    Ouvrir la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le volet de navigation, cliquez sur Bigtable Studio.

  4. Dans le volet Explorateur, développez la table contenant le bundle de schémas, puis développez Bundles de schémas.

  5. À côté du bundle de schémas que vous souhaitez supprimer, cliquez sur le menu d'actions more_vert, puis sur Supprimer.

  6. Dans la boîte de dialogue de confirmation, cliquez sur Supprimer.

gcloud

Pour supprimer un bundle de schémas, utilisez la commande gcloud bigtable schema-bundles delete :

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Remplacez les éléments suivants :

  • SCHEMA_BUNDLE_ID : ID du bundle de schémas à supprimer.
  • INSTANCE_ID : ID de l'instance contenant le bundle de schémas.
  • TABLE_ID : ID de la table contenant le bundle de schémas.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la section Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

try {
  adminClient.deleteSchemaBundle(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

Limites

Les bundles de schémas présentent les limites suivantes :

  • Vous pouvez créer jusqu'à 10 groupes de schémas par table. Cette limite s'applique aux bundles de schémas protobuf et Avro.
  • La taille totale des descripteurs de tampons de protocole sérialisés dans un bundle de schéma ne peut pas dépasser 4 Mo. Il n'existe pas de limite directe au nombre de schémas individuels que vous pouvez inclure dans un bundle, tant que la taille totale du bundle ne dépasse pas cette limite.

Étapes suivantes