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 Protocol Buffers (protobuf) pour interroger des champs individuels dans les messages protobuf stockés sous forme d'octets dans vos colonnes. Pour ce faire, importez 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 protocol buffers, vous définissez la structure de vos 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.
  • Élimine 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 base de code 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éma.

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 la Google Cloud CLI. Une fois que vous avez importé un bundle de schéma dans Bigtable, vous pouvez interroger vos données à l'aide de l'outil de création 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éma, demandez à votre administrateur de vous accorder le rôle IAM 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éma. 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éma, vous devez générer un ensemble de descripteurs à partir de vos fichiers .proto avec 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 pour laquelle vous souhaitez créer un bundle de schéma, cliquez sur le menu d'actions more_vert, puis sur Créer un bundle de schéma.

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

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

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

  7. Cliquez sur Créer.

    Le bundle de schéma 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 : ID unique du nouveau bundle de schéma, qui ne peut pas contenir de caractères 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éma, 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 bundles de schéma, vous devez disposer d'une table Bigtable comportant au moins un bundle de schéma. 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 du 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 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éma.

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

gcloud

Pour obtenir des détails sur un bundle de schéma, 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éma.
  • INSTANCE_ID : ID de l'instance
  • TABLE_ID : ID de la table.

Java

Pour obtenir la définition d'un bundle de schéma, 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 imprimer 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éma dans un tableau

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éma que vous souhaitez afficher.

  5. Développez Regroupements de schémas.

    La liste des bundles de schéma s'affiche dans le tableau. Si la table ne comporte aucun bundle de schéma, la liste Bundles de schémas ne s'affiche pas.

gcloud

Pour afficher la liste des bundles de schéma 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éma d'une table, utilisez la méthode listSchemaBundles. Cette méthode renvoie une liste d'ID de bundle de schéma.

L'exemple suivant montre comment lister les bundles de schéma dans un tableau :

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éma, Bigtable vérifie si le nouvel ensemble de descripteurs est rétrocompatible avec celui existant. Si Bigtable détecte une incompatibilité, la mise à jour échoue et renvoie une erreur FailedPrecondition. Nous vous recommandons de réserver les numéros de champs supprimés pour éviter qu'ils ne soient réutilisés. Pour en savoir plus, consultez Bonnes pratiques concernant les fichiers .proto dans la documentation protobuf.

Si vous êtes sûr que les modifications incompatibles sont sûres et que vous souhaitez forcer une mise à jour, vous pouvez utiliser l'option --ignore-warnings avec gcloud CLI. Toutefois, vous ne pouvez pas forcer les modifications incompatibles si le bundle de schéma est utilisé par une vue matérialisée continue ou une vue logique. Les vues dépendent des définitions de messages du bundle de schéma pour analyser et interroger les données. Par conséquent, les 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éma référencé par une vue, vous devez d'abord mettre à jour ou supprimer les vues référencées.

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 le bundle de schéma, dans le champ Ensemble de descripteurs de fichier (.pb), sélectionnez le nouvel ensemble de descripteurs de fichier protobuf. La taille du fichier ne peut pas dépasser 4 Mo.

  7. Cliquez sur Enregistrer.

gcloud

Pour mettre à jour un bundle de schéma 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éma.
  • TABLE_ID : ID de la table contenant le bundle de schéma.
  • PROTO_DESCRIPTORS_FILE : chemin d'accès au nouveau fichier de jeu de descripteurs.

Facultatif : Pour forcer la mise à jour même en cas de modifications incompatibles, ajoutez l'option --ignore-warnings à la commande. Vous ne pouvez pas forcer les modifications incompatibles si le bundle de schéma 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éma, vous devez d'abord supprimer toutes les vues qui le référencent ou les modifier 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éma, puis développez Bundles de schéma.

  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éma.
  • TABLE_ID : ID de la table contenant le bundle de schéma.

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 ne pouvez pas créer plus de 10 groupes de schémas par table.
  • La taille totale des descripteurs de tampon de protocole sérialisés dans un bundle de schéma ne peut pas dépasser 4 Mo. Le nombre de schémas individuels que vous pouvez inclure dans un bundle n'est pas directement limité, à condition que la taille totale du bundle ne dépasse pas cette limite.

Étapes suivantes