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

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

Dans Bigtable, vous pouvez utiliser des schémas protocol buffer (protobuf) pour interroger des champs individuels dans des 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 du codebase d'un projet spécifique.

Le processus d'utilisation de 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 des ensembles de descripteurs correspondants, consultez Exemples de données.

Le schéma 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 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 à 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 bundle de schémas

gcloud

Pour créer un bundle de schéma, 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 point (".").
  • INSTANCE_ID : ID de l'instance dans laquelle créer le bundle de schéma.
  • TABLE_ID : ID de la table dans laquelle créer le bundle de schéma.
  • PROTO_DESCRIPTORS_FILE : chemin d'accès à l'ensemble de descripteurs généré à l'étape précédente.

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);
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.createSchemaBundle(request);
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to create a schema bundle from a non-existent table: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

Afficher des informations sur les ensembles 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 ensembles de schémas dans un tableau en récupérant la définition d'un seul ensemble de schémas ou en listant tous les ensembles de schémas d'un tableau.

Obtenir la définition du bundle de schéma

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é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(tableId, schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(schemaBundle.getProtoSchema());

  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

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émas dans un tableau, 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 {
  schemaBundleIds = adminClient.listSchemaBundles(tableId);
  for (String schemaBundleId : schemaBundleIds) {
    System.out.println(schemaBundleId);
  }
} 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 bundle 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 elle est incompatible, la mise à jour échoue et une erreur FailedPrecondition s'affiche. 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 les 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 le flag --ignore-warnings avec gcloud CLI.

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 groupe de descripteurs.

Facultatif : Pour forcer la mise à jour même en cas de modifications incompatibles, ajoutez l'option --ignore-warnings à la commande.

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);
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.updateSchemaBundle(request);
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println("Failed to modify a non-existent schema bundle: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

Supprimer un bundle de schémas

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(tableId, 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 bundles 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. Il n'existe aucune limite directe au nombre de schémas individuels que vous pouvez inclure dans un bundle, à condition que la taille totale du bundle ne dépasse pas cette limite.

Étapes suivantes