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

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les schémas Apache Avro dans Bigtable vous permettent d'interroger des champs individuels dans les enregistrements Avro que Bigtable stocke sous forme d'octets sérialisés dans vos colonnes. Pour interroger ces champs, importez vos schémas Avro au format JSON dans un bundle de schémas, une ressource au niveau de la table qui contient un ou plusieurs de vos schémas d'enregistrement Avro. Pour en savoir plus sur les schémas Apache Avro, consultez la documentation Apache Avro.

L'importation d'un bundle de schémas Avro ne modifie pas la façon dont vous écrivez des données dans Bigtable. Vous continuez à écrire des enregistrements Avro sous forme d'octets sérialisés. La charge utile de la cellule ne doit contenir que les octets bruts, sans schéma ni empreinte de schéma intégrés.

Après avoir importé un bundle de schémas dans Bigtable, vous pouvez interroger vos données Avro à l'aide de GoogleSQL pour Bigtable, de vues matérialisées continues ou de vues logiques.

Avant de commencer

Avant de créer et de gérer des bundles de schémas Avro, procédez comme suit :

1. Installez la Google Cloud CLI.

2. Initialisez la gcloud CLI :

   gcloud init
   

3. Assurez-vous de disposer d'une instance et d'une table Bigtable.

4. Activez l'API Cloud Bigtable et l'API Cloud Bigtable Admin :

   gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com
   

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.

Pour obtenir un accès en lecture seule aux bundles de schémas et interroger des enregistrements Avro à l'aide de GoogleSQL pour Bigtable, demandez à votre administrateur de vous accorder le rôle Lecteur Bigtable (roles/bigtable.reader) ou Utilisateur Bigtable (roles/bigtable.user) sur la table.

Ces rôles prédéfinis contiennent les autorisations dont vous avez besoin pour utiliser des bundles de schémas et interroger des données Avro. Pour afficher les autorisations requises, développez la section Autorisations requises :

Autorisations requises

Pour créer et gérer des groupes de schémas, vous devez disposer des autorisations suivantes au niveau de la table ou du groupe de schémas, selon l'opération :

• bigtable.schemaBundles.create : crée des bundles de schémas pour une table
• bigtable.schemaBundles.update : mettre à jour une définition de groupe de schémas
• bigtable.schemaBundles.delete : supprimer un groupe de schémas
• bigtable.schemaBundles.get : obtenir des informations sur un bundle de schémas
• bigtable.schemaBundles.list : lister les bundles de schémas dans une table
• bigtable.schemaBundles.getIamPolicy : obtenir la stratégie IAM d'un groupe de schémas
• bigtable.schemaBundles.setIamPolicy : définit la stratégie IAM pour un groupe de schémas.

Pour lire ou filtrer des enregistrements Avro à l'aide de GoogleSQL pour Bigtable, vous devez disposer des autorisations suivantes :

• bigtable.tables.readRows
• bigtable.instances.executeQuery

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.

Préparer les fichiers de schéma Avro

Avant de créer un bundle de schémas Avro, préparez un ou plusieurs fichiers de schéma Avro au format JSON (AVSC ou JSON). Chaque fichier doit contenir un schéma Avro record valide et autonome au niveau supérieur, avec toutes les dépendances intégrées. Si plusieurs fichiers d'un bundle intègrent le même record ou enum dans le même espace de noms, les définitions doivent correspondre, y compris doc et aliases.

Créer un groupe de schémas Avro

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

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

Remplacez les éléments suivants :

• SCHEMA_BUNDLE_ID : identifiant unique du 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 (.).
• INSTANCE_ID : ID de l'instance contenant la table.
• TABLE_ID : ID de la table dans laquelle créer le bundle de schéma.
• AVRO_SCHEMA_PATH : chemin d'accès à un fichier de schéma Avro au format JSON ou à un répertoire contenant un ou plusieurs fichiers de schéma Avro. Chaque fichier doit être un objet JSON autonome avec toutes les dépendances intégrées.

Afficher des informations sur les bundles de schémas

Vous pouvez afficher 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 de la table.

Obtenir une définition de groupe de schémas Avro

Pour récupérer la définition de schéma Avro au format JSON pour 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

Lister les bundles de schémas dans une table

Pour lister les ID de tous les bundles de schémas d'une table, y compris les bundles de schémas Avro et protobuf, 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

Pour inspecter les définitions de schéma sous-jacentes d'un groupe de schémas spécifique de la liste, exécutez la commande gcloud bigtable schema-bundles describe.

Mettre à jour un groupe de schémas Avro

Pour mettre à jour un bundle de schémas Avro, utilisez la commande gcloud bigtable schema-bundles update. Vous ne pouvez ajouter que de nouvelles définitions d'enregistrement ou d'énumération Avro à un bundle de schémas Avro existant, et vous ne pouvez pas modifier le type d'un bundle de schémas entre Avro et protobuf. Lorsque vous mettez à jour le bundle, vous devez transmettre un fichier ou un répertoire incluant à la fois les nouveaux schémas et tous les schémas existants.

Avertissement : Une fois que vous avez enregistré un enregistrement Avro ou une définition d'énumération dans un groupe de schémas, vous ne pouvez plus le modifier ni le supprimer. Pour éviter les échecs de requêtes d'exécution, la corruption des données ou les champs mal mappés, vous devez lire les enregistrements Avro en utilisant le schéma exact que vous avez utilisé pour les écrire.

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

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éma
• AVRO_SCHEMA_PATH : chemin d'accès à un fichier de schéma Avro au format JSON ou à un répertoire contenant un ou plusieurs fichiers de schéma Avro.

Supprimer un groupe de schémas Avro

Si une vue matérialisée continue ou une vue logique fait référence à un groupe de schémas, vous ne pouvez pas supprimer ce groupe. Avant de supprimer le bundle, supprimez toutes les vues matérialisées continues qui le référencent. Pour toutes les vues logiques qui font référence au bundle, mettez-les à jour pour supprimer la référence ou supprimez-les. Pour en savoir plus, consultez Créer et gérer des vues matérialisées continues ou Créer et gérer des vues logiques.

Avertissement : Une fois que vous avez supprimé un bundle de schémas Avro, vous ne pouvez plus le récupérer.

Pour supprimer un bundle de schémas Avro, 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éma

Tarifs

La création ou la gestion de bundles de schémas Avro n'entraîne aucuns frais supplémentaires. Les frais de bande passante réseau standards s'appliquent aux requêtes et aux réponses. Si vous utilisez le calcul sans serveur Data Boost pour lire des données à partir de Bigtable, vous payez pour les ressources de calcul consommées par vos requêtes. Pour en savoir plus, consultez la page Tarifs de Bigtable.

Limites

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

• Vous pouvez lire et interroger une colonne en tant qu'enregistrements Avro à l'aide de GoogleSQL pour Bigtable, de vues matérialisées continues et de vues logiques. L'API Bigtable ReadRows et les tables externes BigQuery ne sont pas compatibles avec l'analyse Avro côté serveur.
• Vous pouvez créer jusqu'à 10 groupes de schémas par table. Cette limite s'applique aux bundles de schémas Avro et protobuf.
• La taille totale des schémas Avro au format JSON dans un seul groupe de schémas ne peut pas dépasser 4 Mo. Bigtable convertit également le bundle en un ensemble de descripteurs protobuf interne, qui ne peut pas dépasser 4 Mo.
• Bigtable n'est pas compatible avec les types de schémas, structures et modèles de dénomination Avro suivants :
  • Le type fixed et les types logiques, tels que date, duration, time-micros et uuid.
  • Unions à plusieurs branches avec plusieurs types non nuls. Seules les unions acceptant une valeur nulle, telles que ["null", "string"], sont acceptées.
  • Collections imbriquées, telles que des tableaux ou des cartes, qui contiennent d'autres tableaux ou cartes.
  • Tableaux avec des éléments pouvant être nuls. Les mappages avec des valeurs nullables, telles que {"type": "map", "values": ["null", "string"]}, sont acceptés.
  • Tableaux contenant des éléments d'enregistrement vides et sans champ.
  • Définitions d'enregistrements cycliques ou récursifs, ou références d'enregistrements et objets JSON complexes, tels que des enregistrements intégrés, des tableaux, des mappages et des énumérations, imbriqués sur plus de 32 niveaux.
  • Traits de soulignement (_) dans les valeurs namespace Avro.
  • Noms de symboles enum en double dans différents types enum au sein du même espace de noms.
  • Plusieurs champs map dans le même enregistrement dont les noms sont convertis en une même chaîne UpperCamelCase, par exemple my_map, myMap et my__map.
• Lors de l'interrogation des données, Bigtable ignore certains attributs de schéma Avro, tels que les valeurs par défaut des champs (default), aliases, doc et l'ordre de tri (order). Toutefois, si plusieurs fichiers d'un bundle définissent le même record ou enum dans le même espace de noms, leurs définitions doivent correspondre, y compris doc et aliases.

Étapes suivantes

• Découvrez comment interroger des données Avro.
• Découvrez comment créer et gérer des schémas protobuf.
• Consultez la présentation de GoogleSQL pour Bigtable.