Ajouter des tags aux tables et aux ensembles de données

Ce document explique comment utiliser des tags pour appliquer des stratégies Identity and Access Management (IAM) de manière conditionnelle aux tables et aux ensembles de données BigQuery.

Un tag est une paire clé-valeur que vous pouvez associer directement à une table ou à un ensemble de données, ou dont une table ou un ensemble de données peut hériter d'autres ressources Google Cloud. Vous pouvez appliquer des règles de manière conditionnelle selon qu'une ressource possède un tag spécifique. Par exemple, vous pouvez accorder de manière conditionnelle le rôle "Lecteur de données BigQuery" à un compte principal sur n'importe quel ensemble de données doté du tag environment:dev.

Pour en savoir plus sur l'utilisation des tags dans la hiérarchie des ressources Google Cloud, consultez la page Présentation des tags.

Pour accorder des autorisations à de nombreuses ressources BigQuery associées en même temps, y compris à des ressources qui n'existent pas encore, envisagez d'utiliser des conditions IAM.

Autorisations requises

Pour utiliser des tags dans BigQuery, vous devez disposer des autorisations suivantes :

• Pour associer un tag à un ensemble de données, vous devez disposer de l'autorisation IAM bigquery.datasets.createTagBinding sur l'ensemble de données et de l'autorisation resourcemanager.tagValueBindings.create au niveau du projet sur la valeur de tag que vous souhaitez associer.
• Pour associer un tag à une table, vous devez disposer de l'autorisation IAM bigquery.tables.createTagBinding sur la table et de l'autorisation resourcemanager.tagValueBindings.create au niveau du projet sur la valeur de tag que vous souhaitez associer.
• Pour supprimer un tag d'un ensemble de données, vous devez disposer de l'autorisation IAM bigquery.datasets.deleteTagBinding sur l'ensemble de données et de l'autorisation resourcemanager.tagValueBindings.delete au niveau du projet sur la valeur de tag que vous souhaitez supprimer.
• Pour supprimer un tag d'une table, vous devez disposer de l'autorisation IAM bigquery.tables.deleteTagBinding sur la table et de l'autorisation resourcemanager.tagValueBindings.delete au niveau du projet sur la valeur de tag que vous souhaitez supprimer.
• Pour répertorier les tags associés à un ensemble de données ou afficher la section Tags du panneau Modifier les détails d'un ensemble de données, vous avez besoin de l'autorisation IAM bigquery.datasets.listTagBindings.
• Pour répertorier les clés de tag associées à une organisation ou à un projet parent dans le panneau Modifier les détails d'un ensemble de données ou d'une table, vous devez disposer de l'autorisation resourcemanager.tagKeys.list au niveau du parent de la clé de tag et de l'autorisation resourcemanager.tagKeys.get pour chaque clé de tag.
• Pour répertorier les valeurs de tag des clés associées à une organisation ou à un projet parent dans le panneau Modifier les détails d'un ensemble de données ou d'une table, vous devez disposer de l'autorisation resourcemanager.tagValues.list au niveau du parent de la valeur de tag et de l'autorisation resourcemanager.tagValues.get pour chaque valeur de tag.

Les deux rôles IAM prédéfinis suivants incluent toutes les autorisations BigQuery nécessaires :

• Propriétaire de données BigQuery (roles/bigquery.dataOwner)
• Administrateur BigQuery (roles/bigquery.admin)

Les autorisations Resource Manager sont incluses dans le rôle Utilisateur de tags (roles/resourcemanager.tagUser).

Créer des clés et des valeurs de tags

Avant de pouvoir associer un tag, vous devez d'abord créer un tag et configurer sa valeur. Pour créer des clés et des valeurs de tags, consultez les sections Créer un tag et Ajouter des valeurs de tags.

Associer des tags à un ensemble de données

Après avoir créé un tag, vous pouvez l'associer à un ensemble de données. Vous ne pouvez associer qu'une seule valeur de tag à un ensemble de données pour une clé de tag donnée. Vous pouvez associer jusqu'à 50 tags à un ensemble de données.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et sélectionnez un ensemble de données.

3. Dans le panneau Informations sur l'ensemble de données, cliquez sur  Modifier les détails.

4. Dans la section Tags, sélectionnez les tags que vous souhaitez ajouter à l'ensemble de données.

   Remarque : La section Tags n'est pas visible si vous ne possédez pas l'autorisation bigquery.datasets.listTagBindings.

5. Cliquez sur Enregistrer.

gcloud

Pour associer un tag à un ensemble de données à l'aide de la ligne de commande, créez une ressource de liaison de tag à l'aide de la commande gcloud resource-manager tags bindings create :

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Remplacez les éléments suivants :

• TAGVALUE_NAME : ID permanent ou nom de l'espace de noms de la valeur du tag à associer, tel que tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
• RESOURCE_ID : ID complet de l'ensemble de données, avec le nom de domaine de l'API (//bigquery.googleapis.com/) permettant d'identifier le type de ressource (par exemple, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset)
• LOCATION : emplacement de votre ensemble de données

Répertorier les tags associés à un ensemble de données

Les étapes suivantes fournissent une liste de liaisons de tags directement associées à un ensemble de données. Elles ne renvoient aucun tag hérité des ressources parentes.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et sélectionnez un ensemble de données.

   Les tags apparaissent dans le panneau Informations sur l'ensemble de données.

Remarque : Si vous disposez des autorisations bigquery.datasets.listTagBindings, mais pas des autorisations resourcemanager.tagKeys.get et resourcemanager.tagValues.get, seul l'ID permanent du tag est visible.

gcloud

Pour obtenir la liste des liaisons de tags associées à une ressource, exécutez la commande gcloud resource-manager tags bindings list :

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Remplacez les éléments suivants :

• RESOURCE_ID : ID complet de l'ensemble de données, avec le nom de domaine de l'API (//bigquery.googleapis.com/) permettant d'identifier le type de ressource (par exemple, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset)

• LOCATION : emplacement de votre ensemble de données

Le résultat ressemble à ce qui suit :

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

Dissocier les tags d'un ensemble de données

Vous pouvez dissocier un tag d'une ressource en supprimant la ressource de liaison de tag. Pour supprimer un tag, vous devez d'abord le dissocier.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et sélectionnez un ensemble de données.

3. Dans le panneau Informations sur l'ensemble de données, cliquez sur  Modifier les détails.

4. Dans la section Tags, cliquez sur Supprimer l'élément à côté du tag que vous souhaitez supprimer.

5. Cliquez sur Enregistrer.

gcloud

Pour dissocier un tag d'un ensemble de données à l'aide de la ligne de commande, supprimez la liaison de tag à l'aide de la commande gcloud alpha resource-manager tags bindings delete :

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Remplacez les éléments suivants :

• TAGVALUE_NAME : ID permanent ou nom de l'espace de noms de la valeur du tag à associer, tel que tagValues/4567890123 ou 1234567/my_tag_key/my_tag_value
• RESOURCE_ID : ID complet de l'ensemble de données, avec le nom de domaine de l'API (//bigquery.googleapis.com/) permettant d'identifier le type de ressource (par exemple, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset)
• LOCATION : emplacement de votre ensemble de données

Associer des tags lors de la création d'une table

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Après avoir créé un tag, vous pouvez l'associer à une nouvelle table. Vous ne pouvez associer qu'une seule valeur de tag à un ensemble de données pour une clé de tag donnée. Vous pouvez associer jusqu'à 50 tags à une table.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet, puis sélectionnez un ensemble de données.

3. Dans la section Informations sur l'ensemble de données, cliquez sur  Créer une table.

4. Saisissez les informations concernant votre nouvelle table. Pour en savoir plus, consultez Créer et utiliser des tables.

5. Dans la section Tags, sélectionnez les tags que vous souhaitez ajouter à la nouvelle table. Vous ne pouvez pas saisir manuellement les ID de tags à cette étape. Vous ne pouvez sélectionner que des tags de votre projet ou de votre organisation.

6. Cliquez sur Créer la table.

bq

Exécutez la commande bq mk --table avec l'option --add_tags :

bq mk --table \
    --schema=SCHEMA \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Remplacez les éléments suivants :

• SCHEMA : définition de schéma intégrée.
• TAGS : tags que vous associez à la nouvelle table, séparés par des virgules (par exemple, 556741164180/env:prod,myProject/department:sales). Chaque tag doit porter le nom de l'espace de noms associé à la clé et le nom court de la valeur.
• PROJECT_ID : ID du projet dans lequel vous créez une table.
• DATASET_ID : ID de l'ensemble de données dans lequel vous créez une table.
• TABLE_ID : ID de la table que vous créez.

API

Appelez la méthode tables.insert avec une ressource de table définie et incluez les tags dans le champ resource_tags.

Associer des tags à une table existante

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Après avoir créé un tag, vous pouvez l'associer à une table existante. Vous ne pouvez associer qu'une seule valeur de tag à une table pour une clé de tag donnée. Vous pouvez associer jusqu'à 50 tags à une table.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et votre ensemble de données, puis sélectionnez une table.

3. Dans l'onglet Détails, cliquez sur  Modifier les détails.

4. Dans la section Tags, sélectionnez les tags que vous souhaitez ajouter à la table. Vous ne pouvez pas saisir manuellement les ID de tags à cette étape. Vous ne pouvez sélectionner que des tags de votre projet ou de votre organisation.

5. Cliquez sur Enregistrer.

bq

Exécutez la commande bq update avec l'option --add_tags :

bq update \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Remplacez les éléments suivants :

• TAGS : tags que vous associez à la table, séparés par des virgules (par exemple, 556741164180/env:prod,myProject/department:sales). Chaque tag doit porter le nom de l'espace de noms associé à la clé et le nom court de la valeur.
• PROJECT_ID : ID du projet contenant votre table.
• DATASET_ID : ID de l'ensemble de données contenant votre table.
• TABLE_ID : ID de la table que vous mettez à jour.

API

Appelez la méthode tables.update avec une ressource de table définie et incluez les tags dans le champ resource_tags.

Répertorier les tags associés à une table

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez répertorier les tags directement associés à une table. Ce processus ne répertorie pas les tags hérités des ressources parentes.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et votre ensemble de données, puis sélectionnez une table.

   Les tags sont visibles dans l'onglet Détails.

bq

Exécutez la commande bq show, puis recherchez la colonne tags. Si la table ne comporte aucun tag, la colonne tags ne s'affiche pas.

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

Remplacez les éléments suivants :

• PROJECT_ID : ID du projet contenant votre table.
• DATASET_ID : ID de l'ensemble de données contenant votre table.
• TABLE_ID : ID de votre table.

API

Appelez la méthode tables.get avec une ressource de table définie, puis recherchez le champ resource_tags.

Dissocier les tags d'une table

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez dissocier un tag d'une table en supprimant la ressource de liaison de tag. Pour supprimer un tag, vous devez d'abord le dissocier.

Console

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et votre ensemble de données, puis sélectionnez une table.

3. Dans l'onglet Détails, cliquez sur  Modifier les détails.

4. Dans la section Tags, supprimez les tags que vous souhaitez dissocier de la table.

5. Cliquez sur Enregistrer.

bq

Pour supprimer certains tags d'une table, exécutez la commande bq update avec l'option --remove_tags :

bq update \
    --remove_tags=TAG_KEYS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Remplacez les éléments suivants :

• TAG_KEYS : clés de tag que vous dissociez de la table, séparées par des virgules (par exemple, 556741164180/env,myProject/department). Chaque clé de tag doit porter le nom de l'espace de noms associé à la clé.
• PROJECT_ID : ID du projet contenant votre table.
• DATASET_ID : ID de l'ensemble de données contenant votre table.
• TABLE_ID : ID de la table que vous mettez à jour.

Pour supprimer tous les tags d'une table, exécutez la commande bq update avec l'option --clear_all_tags :

bq update \
    --clear_all_tags \
    PROJECT_ID:DATASET_ID.TABLE_ID

API

Appelez la méthode tables.update avec une ressource de table définie et supprimez les tags dans le champ resource_tags. Pour supprimer tous les tags, supprimez le champ resource_tags.

Supprimer les tags

Vous ne pouvez pas supprimer un tag s'il est référencé par un ensemble de données ou une table. Vous devez dissocier toutes les ressources de liaison de tag existantes avant de supprimer la clé ou la valeur du tag. Pour supprimer des clés et des valeurs de tags, consultez la section Supprimer des tags.

Exemple

Supposons que vous soyez administrateur d'une organisation. Vos analystes de données sont tous membres du groupe [e-mail], qui possède le rôle IAM de lecteur de données BigQuery sur le projet userData. Un analyste de données stagiaire est embauché et, conformément aux règles de l'entreprise, il ne doit être autorisé à afficher l'ensemble de données anonymousData que dans le projet userData. Vous pouvez contrôler son accès à l'aide de tags.

1. Créez un tag avec la clé employee_type et la valeur intern :

   

2. Dans la console Google Cloud, accédez à la page IAM.

   Accéder à IAM

3. Recherchez la ligne contenant le stagiaire auquel vous souhaitez restreindre l'accès à l'ensemble de données, puis cliquez sur  Modifier le compte principal sur cette ligne.

4. Dans le menu Rôle, sélectionnez Lecteur de données BigQuery.

5. Cliquez sur Ajouter une condition :

6. Dans les champs Titre et Description, saisissez les valeurs décrivant la condition de tag IAM que vous souhaitez créer.

7. Dans l'onglet Générateur de conditions, cliquez sur Ajouter.

8. Dans le menu Type de condition, sélectionnez Ressource, puis Tag.

9. Dans le menu Opérateur, sélectionnez comporte une valeur.

10. Dans le champ Chemin d'accès de la valeur, saisissez le chemin d'accès de la valeur du tag au format ORGANIZATION/TAG_KEY/TAG_VALUE (par exemple, example.org/employee_type/intern).

    

    Cette condition de tag IAM restreint l'accès du stagiaire aux ensembles de données portant le tag intern.

11. Pour enregistrer la condition de tag, cliquez sur Enregistrer.

12. Pour enregistrer toutes les modifications que vous avez apportées dans le volet Modifier les autorisations, cliquez sur Enregistrer.

13. Pour associer la valeur du tag intern à l'ensemble de données anonymousData, utilisez la ligne de commande pour exécuter la commande gcloud alpha resource-manager tags bindings create :

    gcloud alpha resource-manager tags bindings create \
    --tag-value=tagValues/4567890123 \
    --parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
    --location=US
    

Limites

• Les tags de table ne sont pas compatibles avec les tables BigQuery Omni, les tables des ensembles de données masqués ou les tables temporaires. De plus, les requêtes interrégionales dans BigQuery Omni n'utilisent pas de tags lors des vérifications de contrôle des accès aux tables dans d'autres régions.

• Vous ne pouvez pas utiliser de tags de table avec l'API Cloud Resource Manager.

• Vous pouvez associer jusqu'à 50 tags à un ensemble de données ou à une table.

• Les requêtes génériques ne sont pas acceptées pour les tables contenant des tags.

• Certains services en dehors de BigQuery ne peuvent pas valider correctement les conditions de tag IAM. Si la condition du tag est positive, ce qui signifie qu'un utilisateur ne dispose d'un rôle sur une ressource que si cette dernière possède un tag particulier, l'accès à cette ressource est refusé, quels que soient les tags auxquels elle est associée. Si la condition du tag est négative, ce qui signifie qu'un utilisateur ne dispose d'un rôle sur une ressource que si cette ressource ne possède pas de tag particulier, la condition de tag n'est pas vérifiée.

  Par exemple, Data Catalog ne peut pas vérifier les conditions de tag IAM sur les ensembles de données BigQuery. Supposons qu'une stratégie IAM conditionnelle attribue à un stagiaire le rôle "Lecteur de données BigQuery" sur les ensembles de données portant le tag employee_type=intern. Comme il s'agit d'une condition de tag positive, le stagiaire ne peut pas afficher les ensembles de données en effectuant une recherche dans Data Catalog, même s'ils comportent le tag employee_type=intern. Si la condition de tag a été remplacée par une condition négative afin que le stagiaire ne puisse afficher que les ensembles de données ne portant pas le tag employee_type=intern, la vérification est ignorée complètement et le stagiaire a pu afficher les ensembles de données auxquels il ne pouvait pas accéder normalement dans BigQuery.

  Bonne pratique : Utilisez des conditions de tag IAM positives plutôt que négatives pour éviter d'attribuer involontairement des rôles.

Étapes suivantes

• Pour en savoir plus sur les tags dans Google Cloud, consultez la page Présentation des tags.
• Pour en savoir plus sur l'utilisation des tags, consultez la page Créer et gérer des tags.
• Pour en savoir plus sur le contrôle des accès aux ressources BigQuery avec des conditions IAM, consultez la page Contrôler les accès avec des conditions IAM.