Mettre à jour les propriétés des ensembles de données

Ce document explique comment mettre à jour les propriétés d'un ensemble de données dans BigQuery. Après avoir créé un ensemble de données, vous pouvez mettre à jour les propriétés suivantes :

Contrôle des accès
Modèle de facturation
Délai d'expiration par défaut pour les nouvelles tables
Délai d'expiration de partition par défaut pour les nouvelles tables partitionnées
Mode d'arrondi par défaut pour les nouvelles tables
Description
Libellés
Fenêtres de fonctionnalité temporelle

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Autorisations requises

Pour mettre à jour les propriétés d'un ensemble de données, vous devez disposer des autorisations IAM suivantes :

bigquery.datasets.update
bigquery.datasets.setIamPolicy (obligatoire uniquement lors de la mise à jour des contrôles d'accès d'un ensemble de données dans la console Google Cloud)

Le rôle IAM prédéfini roles/bigquery.dataOwner inclut les autorisations dont vous avez besoin pour mettre à jour les propriétés d'un ensemble de données.

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez mettre à jour les propriétés des ensembles de données que vous créez.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Mettre à jour les descriptions des ensembles de données

Vous pouvez mettre à jour la description d'un ensemble de données comme suit :

Utiliser la console Google Cloud
Utiliser la commande bq update de l'outil de ligne de commande bq
Appeler la méthode API datasets.patch
En utilisant les bibliothèques clientes

Pour mettre à jour la description d'un ensemble de données, procédez comme suit.

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir.
Dans le panneau Détails, cliquez sur Modifier les détails pour modifier le texte de description.

Dans la boîte de dialogue Modifier les détails qui s'affiche, procédez comme suit :
1. Dans le champ Description, saisissez une description ou modifiez la description existante.
2. Pour enregistrer la nouvelle description, cliquez sur Enregistrer.

SQL

Pour mettre à jour la description d'un ensemble de données, utilisez l'instruction ALTER SCHEMA SET OPTIONS pour définir l'option description.

L'exemple suivant définit la description d'un ensemble de données nommé mydataset :

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

Accéder à BigQuery

Dans l'éditeur de requête, saisissez l'instruction suivante :

 ALTER SCHEMA mydataset
 SET OPTIONS (
     description = 'Description of mydataset');

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez la commande bq update avec l'option --description. Si vous mettez à jour un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.

bq update \
--description "string" \
project_id:dataset

Remplacez l'élément suivant :

string : texte qui décrit l'ensemble de données entre guillemets.
project_id : ID de votre projet.
dataset : nom de l'ensemble de données que vous mettez à jour.

Exemples :

Saisissez la commande suivante pour remplacer la description de mydataset par "Description of mydataset". mydataset se trouve dans votre projet par défaut.

bq update --description "Description of mydataset" mydataset

Saisissez la commande suivante pour remplacer la description de mydataset par "Description of mydataset". L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut.

bq update \
--description "Description of mydataset" \
myotherproject:mydataset

API

Appelez datasets.patch, puis mettez à jour la propriété description de la ressource d'ensemble de données. Étant donné que la méthode datasets.update remplace l'intégralité de la ressource d'ensemble de données, la méthode datasets.patch est préférable.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Go.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateDatasetDescription demonstrates how the Description metadata of a dataset can
// be read and modified.
func updateDatasetDescription(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.DatasetMetadataToUpdate{
		Description: "Updated Description.",
	}
	if _, err = ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Créez une instance Dataset.Builder à partir d'une instance Dataset existante à l'aide de la méthode Dataset.toBuilder(). Configurez l'objet pour la génération de l'ensemble de données. Générez l'ensemble de données mis à jour avec la méthode Dataset.Builder.build(), puis appelez la méthode Dataset.update() pour envoyer la mise à jour à l'API.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

public class UpdateDatasetDescription {

  public static void runUpdateDatasetDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String newDescription = "this is the new dataset description";
    updateDatasetDescription(datasetName, newDescription);
  }

  public static void updateDatasetDescription(String datasetName, String newDescription) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Dataset dataset = bigquery.getDataset(datasetName);
      bigquery.update(dataset.toBuilder().setDescription(newDescription).build());
      System.out.println("Dataset description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Dataset description was not updated \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetDescription() {
  // Updates a dataset's description.

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset description
  const description = 'New dataset description.';
  metadata.description = description;

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${datasetId} description: ${newDescription}`);
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Configurez la propriété Dataset.description, puis appelez Client.update_dataset() pour envoyer la mise à jour à l'API.


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.description = "Updated description."
dataset = client.update_dataset(dataset, ["description"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with description '{}'.".format(
        full_dataset_id, dataset.description
    )
)

Mettre à jour les délais d'expiration des tables par défaut

Vous pouvez mettre à jour le délai d'expiration de table par défaut d'un ensemble de données comme suit :

Utiliser la console Google Cloud
Utiliser la commande bq update de l'outil de ligne de commande bq
Appeler la méthode API datasets.patch
Utiliser les bibliothèques clientes

Vous pouvez définir un délai d'expiration de la table par défaut au niveau de l'ensemble de données ou définir le délai d'expiration d'une table lors de sa création. Si vous définissez le délai d'expiration lorsque vous créez la table, le délai par défaut est ignoré. Si vous ne définissez pas de délai d'expiration de table par défaut au niveau de l'ensemble de données et que vous ne définissez pas de délai d'expiration lorsque vous créez la table, celle-ci n'expire jamais et vous devez la supprimer manuellement. Lorsqu'une table expire, elle est supprimée avec toutes les données qu'elle contient.

Lorsque vous mettez à jour le délai d'expiration de table par défaut pour un ensemble de données, prenez en compte les points suivants.

Si vous remplacez la valeur Never (Jamais) par un délai d'expiration défini, toutes les tables qui existent déjà dans l'ensemble de données n'expireront que si le délai d'expiration a été défini sur la table au moment de sa création.
Si vous modifiez la valeur du délai d'expiration par défaut, toutes les tables existantes expireront conformément au délai d'expiration de table d'origine. Le nouveau délai d'expiration de table est appliqué à toutes les nouvelles tables créées dans l'ensemble de données, sauf si vous spécifiez un autre délai d'expiration lors de la création d'une table.

La valeur du délai d'expiration par défaut de table est exprimée différemment selon l'endroit où elle est définie. Parmi les méthodes ci-dessous, utilisez celle qui vous donne le niveau de précision adéquat.

Dans la console Google Cloud, le délai d'expiration est exprimé en jours.
Dans l'outil de ligne de commande bq, le délai d'expiration est exprimé en secondes.
Dans l'API, le délai d'expiration est exprimé en millisecondes.

Pour mettre à jour le délai d'expiration par défaut d'un ensemble de données, procédez comme suit.

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir.
Sur la page Détails, cliquez sur l'icône en forme de crayon à côté de l'onglet Informations sur l'ensemble de données pour modifier le délai d'expiration.
Dans la boîte de dialogue Informations sur l'ensemble de données, dans la section Expiration de la table par défaut, saisissez une valeur pour le paramètre Nombre de jours après la création de la table.
Cliquez sur Enregistrer.

SQL

Pour mettre à jour le délai d'expiration de table par défaut, utilisez l'instruction ALTER SCHEMA SET OPTIONS pour définir l'option default_table_expiration_days.

L'exemple suivant met à jour le délai d'expiration par défaut de la table pour un ensemble de données nommé mydataset.

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

Accéder à BigQuery

Dans l'éditeur de requête, saisissez l'instruction suivante :

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_table_expiration_days = 3.75);

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour mettre à jour le délai d'expiration par défaut des tables nouvellement créées dans un ensemble de données, saisissez la commande bq update avec l'option --default_table_expiration. Si vous mettez à jour un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.

bq update \
--default_table_expiration integer \
project_id:dataset

Remplacez l'élément suivant :

integer : durée de vie par défaut (en secondes) des tables nouvellement créées. La valeur minimale est de 3 600 secondes (une heure). Le délai d'expiration correspond à l'heure UTC actuelle plus la valeur entière. Spécifiez 0 pour supprimer le délai d'expiration existant. Toutes les tables créées dans l'ensemble de données sont supprimées integer secondes après leur création. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration pour la table lors de sa création.
project_id : ID de votre projet.
dataset : nom de l'ensemble de données que vous mettez à jour.

Exemples :

Pour les nouvelles tables créées dans mydataset, saisissez la commande suivante pour définir le délai d'expiration de table par défaut sur deux heures (7 200 secondes) à partir de l'heure actuelle. L'ensemble de données se trouve dans votre projet par défaut.

bq update --default_table_expiration 7200 mydataset

bq update --default_table_expiration 7200 myotherproject:mydataset

API

Appelez datasets.patch, puis mettez à jour la propriété defaultTableExpirationMs de la ressource d'ensemble de données. Dans l'API, le délai d'expiration est exprimé en millisecondes. Étant donné que la méthode datasets.update remplace l'intégralité de la ressource d'ensemble de données, la méthode datasets.patch est préférable.

Go

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// updateDatasetDefaultExpiration demonstrats setting the default expiration of a dataset
// to a specific retention period.
func updateDatasetDefaultExpiration(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.DatasetMetadataToUpdate{
		DefaultTableExpiration: 24 * time.Hour,
	}
	if _, err := client.Dataset(datasetID).Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Configurez le délai d'expiration par défaut avec la méthode Dataset.Builder.setDefaultTableLifetime().

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.concurrent.TimeUnit;

public class UpdateDatasetExpiration {

  public static void runUpdateDatasetExpiration() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    updateDatasetExpiration(datasetName);
  }

  public static void updateDatasetExpiration(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Update dataset expiration to one day
      Long newExpiration = TimeUnit.MILLISECONDS.convert(1, TimeUnit.DAYS);

      Dataset dataset = bigquery.getDataset(datasetName);
      bigquery.update(dataset.toBuilder().setDefaultTableLifetime(newExpiration).build());
      System.out.println("Dataset description updated successfully to " + newExpiration);
    } catch (BigQueryException e) {
      System.out.println("Dataset expiration was not updated \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetExpiration() {
  // Updates the lifetime of all tables in the dataset, in milliseconds.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Set new dataset metadata
  const expirationTime = 24 * 60 * 60 * 1000;
  metadata.defaultTableExpirationMs = expirationTime.toString();

  const [apiResponse] = await dataset.setMetadata(metadata);
  const newExpirationTime = apiResponse.defaultTableExpirationMs;

  console.log(`${datasetId} expiration: ${newExpirationTime}`);
}

Python

Configurez la propriété Dataset.default_table_expiration_ms, puis appelez Client.update_dataset() pour envoyer la mise à jour à l'API.


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = 'your-project.your_dataset'

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.default_table_expiration_ms = 24 * 60 * 60 * 1000  # In milliseconds.

dataset = client.update_dataset(
    dataset, ["default_table_expiration_ms"]
)  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset {} with new expiration {}".format(
        full_dataset_id, dataset.default_table_expiration_ms
    )
)

Mettre à jour les délais d'expiration des partitions par défaut

Vous pouvez mettre à jour le délai d'expiration de partition par défaut d'un ensemble de données comme suit :

Utiliser la commande bq update de l'outil de ligne de commande bq
Appeler la méthode API datasets.patch
Utiliser les bibliothèques clientes

La définition ou la mise à jour du délai d'expiration de partition par défaut d'un ensemble de données n'est actuellement pas possible avec la console Google Cloud.

Vous pouvez définir, au niveau de l'ensemble de données, un délai d'expiration de partition par défaut qui affecte l'ensemble des tables partitionnées nouvellement créées. Vous pouvez également définir un délai d'expiration de partition pour des tables individuelles au moment de leur création. Si vous définissez à la fois un délai d'expiration de partition par défaut au niveau de l'ensemble de données et un délai d'expiration de table par défaut au niveau de l'ensemble de données, les nouvelles tables partitionnées n'auront qu'un délai d'expiration de partition. Si les deux options sont définies, le délai d'expiration de partition par défaut remplace celui appliqué aux tables.

Si vous définissez le délai d'expiration de partition lorsque vous créez la table partitionnée, cette valeur remplace le délai d'expiration de partition par défaut au niveau de l'ensemble de données, s'il existe.

Si vous ne définissez pas de délai d'expiration de partition par défaut au niveau de l'ensemble de données ni de délai d'expiration de partition lors de la création de la table, les partitions n'expirent jamais et vous devez les supprimer manuellement.

Lorsque vous définissez un délai d'expiration de partition par défaut sur un ensemble de données, celui-ci s'applique à toutes les partitions de toutes les tables partitionnées créées dans l'ensemble de données. Lorsque vous définissez le délai d'expiration de partition sur une table, celui-ci s'applique à toutes les partitions créées dans la table spécifiée. Actuellement, vous ne pouvez pas appliquer différents délais d'expiration à différentes partitions de la même table.

Lorsque vous mettez à jour le délai d'expiration de partition par défaut d'un ensemble de données, prenez en compte les points suivants :

Si vous remplacez la valeur never (Jamais) par un délai d'expiration défini, toutes les partitions qui existent déjà dans les tables partitionnées de l'ensemble de données n'expireront que si le délai d'expiration de partition a été défini sur la table au moment de sa création.
Si vous modifiez la valeur du délai d'expiration de partition par défaut, toutes les partitions des tables partitionnées existantes expirent conformément au délai d'expiration de partition par défaut d'origine. Le nouveau délai d'expiration de partition par défaut est appliqué à toutes les nouvelles tables partitionnées créées dans l'ensemble de données, sauf si vous spécifiez un autre délai d'expiration de partition sur la table au moment de la création de celle-ci.

La valeur du délai d'expiration de partition par défaut est exprimée différemment selon l'endroit où elle est définie. Parmi les méthodes ci-dessous, utilisez celle qui vous donne le niveau de précision adéquat.

Dans l'outil de ligne de commande bq, le délai d'expiration est exprimé en secondes.
Dans l'API, le délai d'expiration est exprimé en millisecondes.

Pour mettre à jour le délai d'expiration de partition par défaut d'un ensemble de données, procédez comme suit :

Console

La mise à jour du délai d'expiration de partition par défaut d'un ensemble de données n'est actuellement pas possible dans la console Google Cloud.

SQL

Pour mettre à jour le délai d'expiration de la partition par défaut, utilisez l'instruction ALTER SCHEMA SET OPTIONS pour définir l'option default_partition_expiration_days.

L'exemple suivant met à jour le délai d'expiration par défaut de la partition pour un ensemble de données nommé mydataset :

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

Accéder à BigQuery

Dans l'éditeur de requête, saisissez l'instruction suivante :

 ALTER SCHEMA mydataset
 SET OPTIONS(
     default_partition_expiration_days = 3.75);

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour mettre à jour le délai d'expiration par défaut d'un ensemble de données, saisissez la commande bq update avec l'option --default_partition_expiration. Si vous mettez à jour un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.

bq update \
--default_partition_expiration integer \
project_id:dataset

Remplacez l'élément suivant :

integer : durée de vie par défaut (en secondes) des partitions des tables partitionnées nouvellement créées. Aucune valeur minimale n'est définie pour cette option. Spécifiez 0 pour supprimer le délai d'expiration existant. Toutes les partitions des tables partitionnées nouvellement créées sont supprimées integer secondes après la date UTC des partitions. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration de partition sur la table lors de sa création.
project_id : ID de votre projet.
dataset : nom de l'ensemble de données que vous mettez à jour.

Exemples :

Saisissez la commande suivante pour définir le délai d'expiration de partition par défaut pour les nouvelles tables partitionnées créées dans mydataset sur 26 heures (93 600 secondes). L'ensemble de données se trouve dans votre projet par défaut.

bq update --default_partition_expiration 93600 mydataset

bq update --default_partition_expiration 93600 myotherproject:mydataset

API

Appelez datasets.patch, puis mettez à jour la propriété defaultPartitionExpirationMs de la ressource d'ensemble de données. Le délai d'expiration est exprimé en millisecondes. Étant donné que la méthode datasets.update remplace l'intégralité de la ressource d'ensemble de données, la méthode datasets.patch est préférable.

Mettre à jour le mode d'arrondi

Vous pouvez mettre à jour le mode d'arrondi par défaut d'un ensemble de données à l'aide de l'instruction LDD ALTER SCHEMA SET OPTIONS. L'exemple suivant met à jour le mode d'arrondi par défaut pour mydataset en ROUND_HALF_EVEN.

ALTER SCHEMA mydataset
SET OPTIONS (
  default_rounding_mode = "ROUND_HALF_EVEN");

Cela définit le mode d'arrondi par défaut pour les nouvelles tables créées dans l'ensemble de données. Cela n'a aucun impact sur les nouvelles colonnes ajoutées aux tables existantes. Cette option est ignorée si vous définissez le mode d'arrondi par défaut sur une table de l'ensemble de données.

Mettre à jour les contrôles d'accès d'un ensemble de données

La procédure de mise à jour des contrôles d'accès d'un ensemble de données est très semblable à la procédure d'application de ces contrôles d'accès. Les contrôles d'accès ne peuvent pas être appliqués lors de la création de l'ensemble de données à l'aide de la console Google Cloud ou de l'outil de ligne de commande bq. Vous devez d'abord créer l'ensemble de données, puis mettre à jour les contrôles d'accès correspondants. L'API vous permet de mettre à jour les contrôles d'accès des ensembles de données en appelant la méthode datasets.patch.

Lorsque vous mettez à jour les contrôles d'accès d'un ensemble de données, vous pouvez modifier l'accès pour les entités suivantes :

Comptes principaux IAM :
- Adresse e-mail du compte Google : permet à un compte Google individuel d'accéder à l'ensemble de données
- Groupe Google : permet à tous les membres d'un groupe Google d'accéder à l'ensemble de données
- Domaine Google Workspace : permet à tous les utilisateurs et groupes d'un domaine Google d'accéder à l'ensemble de données
- Compte de service : permet à un compte de service d'accéder à l'ensemble de données
- Tous les utilisateurs : saisissez allUsers pour accorder l'accès au grand public
- Tous les comptes Google : saisissez allAuthenticatedUsers pour autoriser l'accès à tous les utilisateurs connectés à un compte Google
Types de ressources :
- Ensembles de données autorisés : permet à un ensemble de données autorisé d'accéder à l'ensemble de données
- Vues autorisées : permet à une vue autorisée d'accéder à l'ensemble de données
- Fonctions autorisées : permet à une fonction définie par l'utilisateur autorisée ou à une fonction de table d'accéder à l'ensemble de données.

Pour mettre à jour les contrôles d'accès sur un ensemble de données, procédez comme suit.

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir.
Cliquez sur Partager l'ensemble de données.
Dans la boîte de dialogue Partager l'ensemble de données, développez la liste des entrées existantes, puis cliquez sur l'icône de suppression (corbeille) pour les supprimer.
Dans la boîte de dialogue Partager l'ensemble de données, suivez ces étapes pour ajouter de nouvelles entrées :
1. Saisissez le nom de l'entité dans la zone Ajouter des comptes principaux.
2. Pour Sélectionner un rôle, choisissez un rôle IAM approprié dans la liste. Pour en savoir plus sur les autorisations attribuées à chaque rôle BigQuery prédéfini, consultez la page Rôles et autorisations prédéfinis.
3. Cliquez sur Ajouter.
Pour ajouter une vue autorisée, cliquez sur l'onglet Vue autorisée, saisissez les noms du projet, de l'ensemble de données et de la vue, puis cliquez sur Ajouter.
Lorsque vous avez terminé l'ajout ou la suppression de vos contrôles d'accès, cliquez sur OK.

bq

Écrivez les informations sur l'ensemble de données existant (y compris les contrôles d'accès) dans un fichier JSON à l'aide de la commande show. Si l'ensemble de données se trouve dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.
```
bq show \
--format=prettyjson \
project_id:dataset > path_to_file
```
Remplacez l'élément suivant :
- project_id : ID de votre projet.
- dataset : nom de votre ensemble de données.
- path_to_file : chemin d'accès au fichier JSON sur votre ordinateur local.
Exemples :

Saisissez la commande suivante pour écrire les contrôles d'accès pour mydataset dans un fichier JSON. mydataset se trouve dans votre projet par défaut.
```
bq show --format=prettyjson mydataset > /tmp/mydataset.json
```
Saisissez la commande suivante pour écrire les contrôles d'accès pour mydataset dans un fichier JSON. mydataset se trouve dans myotherproject.
```
bq show --format=prettyjson \
myotherproject:mydataset > /tmp/mydataset.json
```

Apportez vos modifications à la section "access" du fichier JSON. Vous pouvez ajouter ou supprimer n'importe quelle entrée specialGroup : projectOwners, projectWriters, projectReaders et allAuthenticatedUsers. Vous pouvez également ajouter, supprimer ou modifier l'un des éléments suivants : userByEmail, groupByEmail et domain.

Par exemple, la section d'accès du fichier JSON d'un ensemble de données ressemblerait à ceci :

{
 "access": [
  {
   "role": "READER",
   "specialGroup": "projectReaders"
  },
  {
   "role": "WRITER",
   "specialGroup": "projectWriters"
  },
  {
   "role": "OWNER",
   "specialGroup": "projectOwners"
  }
  {
   "role": "READER",
   "specialGroup": "allAuthenticatedUsers"
  }
  {
   "role": "READER",
   "domain": "[DOMAIN_NAME]"
  }
  {
   "role": "WRITER",
   "userByEmail": "[USER_EMAIL]"
  }
  {
   "role": "READER",
   "groupByEmail": "[GROUP_EMAIL]"
  }
 ],
}

Une fois vos modifications terminées, exécutez la commande update et incluez le fichier JSON à l'aide de l'option --source. Si l'ensemble de données se trouve dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.
Attention : Lorsque vous appliquez le fichier JSON contenant les contrôles d'accès modifiés, les contrôles d'accès existants sont écrasés.
```
bq update --source path_to_file project_id:dataset
```
Remplacez l'élément suivant :
- path_to_file : chemin d'accès au fichier JSON sur votre ordinateur local.
- project_id : ID de votre projet.
- dataset : nom de votre ensemble de données.
Exemples :

Saisissez la commande suivante pour mettre à jour les contrôles d'accès pour mydataset. mydataset se trouve dans votre projet par défaut.
```
bq update --source /tmp/mydataset.json mydataset
```
Saisissez la commande suivante pour mettre à jour les contrôles d'accès pour mydataset. mydataset se trouve dans myotherproject.
```
bq update --source /tmp/mydataset.json myotherproject:mydataset
```
Pour vérifier les modifications apportées aux contrôles d'accès, saisissez à nouveau la commande show sans écrire les informations dans un fichier.
```
bq show --format=prettyjson dataset
```
ou
```
bq show --format=prettyjson project_id:dataset
```

API

Appelez la méthode datasets.patch, puis mettez à jour la propriété access dans la ressource d'ensemble de données.

Comme la méthode datasets.update remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode datasets.patch.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateDatasetAccessControl demonstrates how the access control policy of a dataset
// can be amended by adding an additional entry corresponding to a specific user identity.
func updateDatasetAccessControl(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       bigquery.ReaderRole,
			EntityType: bigquery.UserEmailEntity,
			Entity:     "sample.bigquery.dev@gmail.com"},
		),
	}

	// Leverage the ETag for the update to assert there's been no modifications to the
	// dataset since the metadata was originally read.
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Configurez les contrôles d'accès avec la méthode Dataset.Builder.setAcl().

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Role;
import com.google.cloud.bigquery.Acl.User;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.ArrayList;

public class UpdateDatasetAccess {

  public static void runUpdateDatasetAccess() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    updateDatasetAccess(datasetName);
  }

  public static void updateDatasetAccess(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Dataset dataset = bigquery.getDataset(datasetName);

      // Create a new ACL granting the READER role to "sample.bigquery.dev@gmail.com"
      // For more information on the types of ACLs available see:
      // https://cloud.google.com/storage/docs/access-control/lists
      Acl newEntry = Acl.of(new User("sample.bigquery.dev@gmail.com"), Role.READER);

      // Get a copy of the ACLs list from the dataset and append the new entry
      ArrayList<Acl> acls = new ArrayList<>(dataset.getAcl());
      acls.add(newEntry);

      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("Dataset Access Control updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset Access control was not updated \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateDatasetAccess() {
  // Updates a datasets's access controls.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Create new role metadata
  const newRole = {
    role: 'READER',
    entity_type: 'userByEmail',
    userByEmail: 'sample.bigquery.dev@gmail.com',
  };

  // Retreive current dataset metadata
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add new role to role acess array
  metadata.access.push(newRole);
  const [apiResponse] = await dataset.setMetadata(metadata);
  const newAccessRoles = apiResponse.access;
  newAccessRoles.forEach(role => console.log(role));
}

Python

Définissez la propriété dataset.access_entries avec les contrôles d'accès pour un ensemble de données. Appelez ensuite la fonction client.update_dataset() pour mettre à jour la propriété.


# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom
# you are adding access. Alternatively, to the JSON REST API representation
# of the entity, such as a view's table reference.
entity_id = "user-or-group-to-add@example.com"

from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Set entity_type to the type of entity you are granting access to.
# Common types include:
#
# * "userByEmail" -- A single user or service account. For example "fred@example.com"
# * "groupByEmail" -- A group of users. For example "example@googlegroups.com"
# * "view" -- An authorized view. For example
#       {"projectId": "p", "datasetId": "d", "tableId": "v"}
#
# For a complete reference, see the REST API reference documentation:
# https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#Dataset.FIELDS.access
entity_type = EntityTypes.GROUP_BY_EMAIL

# TODO(developer): Set role to a one of the "Basic roles for datasets"
# described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
role = "READER"

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ["access_entries"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

Mettre à jour les fenêtres de fonctionnalité temporelle

Vous pouvez mettre à jour la fenêtre de fonctionnalité temporelle d'un ensemble de données comme suit :

Utiliser la console Google Cloud
Utilisez l'instruction ALTER SCHEMA SET OPTIONS.
Utiliser la commande bq update de l'outil de ligne de commande bq.
Appeler la méthode API datasets.patch ou datasets.update La méthode update remplace l'intégralité de la ressource d'ensemble de données, tandis que la méthode patch ne remplace que les champs fournis dans la ressource d'ensemble de données fournie.

Pour plus d'informations sur la fenêtre de fonctionnalité temporelle, consultez la section Configurer la fenêtre de fonctionnalité temporelle.

Pour mettre à jour la fenêtre de fonctionnalité temporelle pour un ensemble de données :

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir.
Dans le panneau Détails, cliquez sur Modifier les détails.
Développez les Options avancées, puis sélectionnez la fenêtre de fonctionnalité temporelle à utiliser.
Cliquez sur Enregistrer.

SQL

Utilisez l'instruction ALTER SCHEMA SET OPTIONS avec l'option max_time_travel_hours pour spécifier la fenêtre de fonctionnalité temporelle pendant la modification d'un ensemble de données. La valeur max_time_travel_hours doit être un entier exprimé par des multiples de 24 (48, 72, 96, 120, 144, 168) entre 48 (2 jours) et 168 (7 jours).

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
ALTER SCHEMA DATASET_NAME
SET OPTIONS(
  max_time_travel_hours = HOURS);
```
Remplacez les éléments suivants :
- DATASET_NAME : nom de l'ensemble de données que vous mettez à jour.
- HOURS par la durée de la fenêtre de fonctionnalité temporelle, en heures.
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez la commande bq update avec l'option --max_time_travel_hours pour spécifier la fenêtre de fonctionnalité temporelle pendant la modification d'un ensemble de données. La valeur --max_time_travel_hours doit être un entier exprimé par des multiples de 24 (48, 72, 96, 120, 144, 168) entre 48 (2 jours) et 168 (7 jours).

bq update \
--dataset=true --max_time_travel_hours=HOURS \
PROJECT_ID:DATASET_NAME

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
DATASET_NAME : nom de l'ensemble de données que vous mettez à jour.
HOURS par la durée de la fenêtre de fonctionnalité temporelle, en heures.

API

Appelez la méthode datasets.patch ou datasets.update avec une ressource d'ensemble de données dans laquelle vous avez spécifié une valeur pour le champ maxTimeTravelHours. La valeur maxTimeTravelHours doit être un entier exprimé par des multiples de 24 (48, 72, 96, 120, 144, 168) entre 48 (2 jours) et 168 (7 jours).

Mettre à jour les modèles de facturation du stockage

Vous pouvez modifier le modèle de facturation du stockage d'un ensemble de données. Définissez la valeur storage_billing_model sur PHYSICAL pour utiliser des octets physiques lors du calcul des modifications de l'espace de stockage ou sur LOGICAL pour utiliser des octets logiques. LOGICAL est la valeur par défaut.

Lorsque vous modifiez le modèle de facturation d'un ensemble de données, la prise en compte de la modification prend 24 heures.

Une fois que vous avez modifié le modèle de facturation du stockage d'un ensemble de données, vous devez attendre 14 jours avant de pouvoir modifier à nouveau le modèle de facturation du stockage.

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir.
Dans le panneau Détails, cliquez sur Modifier les détails.
Développez les Options avancées, puis sélectionnez Activer le modèle de facturation du stockage physique pour utiliser la facturation du stockage physique, ou désélectionnez l'option pour utiliser la facturation du stockage logique.
Cliquez sur Enregistrer.

SQL

Pour mettre à jour le modèle de facturation d'un ensemble de données, utilisez l'instruction ALTER SCHEMA SET OPTIONS et définissez l'option storage_billing_model :

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
ALTER SCHEMA DATASET_NAME
SET OPTIONS(
 storage_billing_model = 'BILLING_MODEL');
```
Remplacez les éléments suivants :
- DATASET_NAME par le nom de l'ensemble de données que vous modifiez.
- BILLING_MODEL par le type de stockage que vous souhaitez utiliser (LOGICAL ou PHYSICAL).
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

Pour mettre à jour le modèle de facturation de l'espace de stockage de tous les ensembles de données d'un projet, utilisez la requête SQL suivante pour chaque région où se trouvent les ensembles de données :

FOR record IN
 (SELECT CONCAT(catalog_name, '.', schema_name) AS dataset_path
 FROM PROJECT_ID.region-REGION.INFORMATION_SCHEMA.SCHEMATA)
DO
 EXECUTE IMMEDIATE
   "ALTER SCHEMA `" || record.dataset_path || "` SET OPTIONS(storage_billing_model = 'BILLING_MODEL')";
END FOR;

Remplacez les éléments suivants :

PROJECT_ID par votre ID de projet
REGION par un qualificatif de région
BILLING_MODEL par le type de stockage que vous souhaitez utiliser (LOGICAL ou PHYSICAL).

bq

Pour mettre à jour le modèle de facturation d'un ensemble de données, exécutez la commande bq update en définissant l'option --storage_billing_model :

bq update -d --storage_billing_model=BILLING_MODEL PROJECT_ID:DATASET_NAME

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
DATASET_NAME : nom de l'ensemble de données que vous mettez à jour.
BILLING_MODEL : type de stockage que vous souhaitez utiliser (LOGICAL ou PHYSICAL)

API

Appelez la méthode datasets.update avec une ressource d'ensemble de données définie, où le champ storageBillingModel est défini.

L'exemple suivant montre comment appeler datasets.update avec curl :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X PUT https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID -d '{"datasetReference": {"projectId": "PROJECT_ID", "datasetId": "DATASET_NAME"}, "storageBillingModel": "BILLING_MODEL"}'

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
DATASET_NAME : nom de l'ensemble de données que vous mettez à jour.
BILLING_MODEL : type de stockage que vous souhaitez utiliser (LOGICAL ou PHYSICAL)

Sécurité des ensembles de données

Pour savoir comment contrôler l'accès aux ensembles de données dans BigQuery, consultez la page Contrôler l'accès aux ensembles de données. Pour en savoir plus sur le chiffrement des données, consultez la page Chiffrement au repos.

Étapes suivantes

Pour en savoir plus sur la création des ensembles de données, consultez la page Créer des ensembles de données.
Pour en savoir plus sur la gestion des ensembles de données, consultez la page Gérer les ensembles de données.