Mettre à jour des libellés

Cette page explique comment mettre à jour les libellés des ressources BigQuery.

Mettre à jour les libellés d'un ensemble de données

Vous pouvez mettre à jour un libellé d'ensemble de données de l'une des manières suivantes :

  • À l'aide de la console GCP ou de l'UI Web classique de BigQuery
  • En utilisant la commande bq update de l'outil de ligne de commande
  • En appelant la méthode API datasets.patch
  • En utilisant les bibliothèques clientes

Autorisations requises

Pour mettre à jour un libellé d'ensemble de données, vous devez au minimum disposer des autorisations bigquery.datasets.update. Les rôles Cloud IAM prédéfinis suivants incluent des autorisations bigquery.datasets.update :

  • bigquery.dataOwner
  • bigquery.admin

En outre, si un utilisateur possède des autorisations bigquery.datasets.create, lorsqu'il crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. Un accès bigquery.dataOwner permet à l'utilisateur de mettre à jour les libellés d'un ensemble de données.

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

Mettre à jour un libellé d'ensemble de données

Pour mettre à jour les libellés d'un ensemble de données, procédez comme suit :

Console

  1. Dans la console GCP, sélectionnez l'ensemble de données.

  2. Sur la page des détails de l'ensemble de données, cliquez sur l'icône en forme de crayon située à droite de Labels (Libellés).

    Icône en forme de crayon pour modifier un libellé

  3. Dans la boîte de dialogue Edit labels (Modifier les libellés), effectuez les opérations suivantes :

    • Pour attribuer des libellés supplémentaires, cliquez sur Add label (Ajouter un libellé). Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
    • Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
    • Cliquez sur Update (Mettre à jour) pour enregistrer vos modifications.

Interface utilisateur classique

  1. Dans l'interface utilisateur Web, sélectionnez l'ensemble de données.

  2. Sur la page Dataset Details (Détails de l'ensemble de données), cliquez sur le bouton Edit (Modifier) situé à droite du champ Labels (Libellés).

    Modifier les libellés

  3. Dans la boîte de dialogue Edit Labels (Modifier les libellés) :

    • Pour appliquer des libellés supplémentaires, cliquez sur Add Label (Ajouter un libellé). Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
    • Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
    • Cliquez sur OK.

      Nouveau libellé

CLI

Pour ajouter des libellés supplémentaires ou pour mettre à jour un libellé d'ensemble de données, exécutez la commande bq update en spécifiant l'indicateur set_label. Répétez l'indicateur pour ajouter ou mettre à jour plusieurs libellés.

Si l'ensemble de données se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : [PROJECT_ID]:[DATASET].

bq update \
--set_label key:value \
project_id:dataset

Où :

  • key:value correspond à une paire clé/valeur pour un libellé que vous souhaitez ajouter ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
  • project_id est l'ID du projet.
  • dataset est le nom de l'ensemble de données que vous mettez à jour.

Exemple :

Pour mettre à jour le libellé department sur l'ensemble de données mydataset, saisissez la commande bq update et spécifiez department comme clé de libellé. Par exemple, si vous souhaitez remplacer le libellé department:shipping par department:logistics, saisissez la commande ci-dessous. L'ensemble de données mydataset se trouve dans le projet myotherproject, et non dans votre projet par défaut.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

Le résultat est semblable à ce qui suit.

Dataset 'myotherproject:mydataset' successfully updated.

API

Pour ajouter des libellés ou mettre à jour un libellé associé à un ensemble de données existant, appelez la méthode datasets.patch, puis ajoutez ou mettez à jour la propriété labels de 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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le 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 Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.DatasetMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {"color": "green"}
dataset.labels = labels

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

Mettre à jour des libellés de table et de vue

Vous pouvez mettre à jour un libellé après la création d'une table ou d'une vue de l'une des manières suivantes :

  • À l'aide de la console GCP ou de l'UI Web classique de BigQuery
  • En utilisant la commande bq update de l'outil de ligne de commande
  • En appelant la méthode API tables.patch
    • Comme les vues sont traitées comme des ressources de table, la méthode tables.patch permet de modifier à la fois des vues et des tables.
  • Utiliser les bibliothèques clientes

Autorisations requises

Pour mettre à jour un libellé de table ou de vue, vous devez au minimum disposer des autorisations bigquery.tables.update. Les rôles Cloud IAM prédéfinis suivants incluent des autorisations bigquery.tables.update :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

En outre, si un utilisateur possède des autorisations bigquery.datasets.create, lorsqu'il crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. L'accès bigquery.dataOwner donne à l'utilisateur la possibilité de mettre à jour des libellés d'ensembles de données et les libellés des tables et vues qu'ils contiennent.

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

Mettre à jour un libellé de table ou de vue

Pour mettre à jour un libellé de table ou de vue, procédez comme suit :

Console

  1. Dans la console GCP, sélectionnez la table ou la vue.

  2. Cliquez sur l'onglet Details (Détails), puis sur l'icône représentant un crayon à droite de Labels (Libellés).

  3. Dans la boîte de dialogue Edit labels (Modifier les libellés), effectuez les opérations suivantes :

    • Pour attribuer des libellés supplémentaires, cliquez sur Add label (Ajouter un libellé). Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez exploiter la même clé pour plusieurs tables ou vues au sein de différents ensembles de données.
    • Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
    • Cliquez sur Update (Mettre à jour) pour enregistrer vos modifications.

Interface utilisateur classique

  1. Dans l'UI Web, sélectionnez la table ou la vue.

  2. Sur la page des détails, cliquez sur le bouton Edit (Modifier) à droite du champ Labels (Libellés). L'exemple ci-dessous vous montre les détails d'une table.

    Modifier les libellés

  3. Dans la boîte de dialogue Edit Labels (Modifier les libellés), effectuez les opérations suivantes :

    • Pour ajouter des libellés, cliquez sur Add Label (Ajouter un libellé). Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez exploiter la même clé pour plusieurs tables ou vues au sein de différents ensembles de données.
    • Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
    • Cliquez sur OK.

      Nouveau libellé

CLI

Pour ajouter des libellés ou pour mettre à jour un libellé de table ou de vue, exécutez la commande bq update en spécifiant l'indicateur set_label. Répétez l'indicateur pour ajouter ou mettre à jour plusieurs libellés.

Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : project_id:dataset.

bq update \
--set_label key:value \
project_id:dataset.table_or_view

Où :

  • key:value correspond à une paire clé/valeur pour un libellé que vous souhaitez ajouter ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
  • project_id est l'ID du projet.
  • dataset est le nom de l'ensemble de données qui contient la table ou la vue que vous mettez à jour.
  • table_or_view est le nom de la table ou de la vue que vous mettez à jour.

Exemple :

Pour mettre à jour le libellé department de la table mytable, saisissez la commande bq update et spécifiez department comme clé de libellé. Par exemple, pour remplacer le libellé department:shipping par department:logistics pour la table mytable, saisissez la commande suivante. La table mytable se trouve dans le projet myotherproject, et non dans votre projet par défaut.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

Le résultat ressemble à ceci :

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Pour ajouter ou mettre à jour un libellé pour une table ou une vue existante, appelez la méthode tables.patch et ajoutez ou mettez à jour la propriété labels de la ressource de table.

Comme les vues sont traitées comme des ressources de table, la méthode tables.patch permet de modifier à la fois des vues et des tables.

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

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le 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 Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tbl := client.Dataset(datasetID).Table(tableID)
meta, err := tbl.Metadata(ctx)
if err != nil {
	return err
}

update := bigquery.TableMetadataToUpdate{}
update.SetLabel("color", "green")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

Mettre à jour des libellés de tâche

Actuellement, il n'est pas possible de mettre à jour des libellés de tâches. Pour mettre à jour le libellé d'une tâche, soumettez à nouveau la tâche en question en spécifiant un nouveau libellé.

Convertir des libellés en tags

Un libellé qui comporte une clé avec une valeur vide fait office de tag. Vous pouvez créer un libellé sans valeur ou convertir un libellé existant en tag sur un ensemble de données, une table ou une vue. En revanche, vous ne pouvez pas convertir un libellé de tâche en tag.

Les tags peuvent s'avérer utiles lorsque vous attribuez des libellés à une ressource, mais n'avez pas besoin d'utiliser le format key:value. Par exemple, si vous disposez d'une table qui contient des données de test utilisées par plusieurs groupes (assistance, développement, etc.), vous pouvez lui attribuer le tag test_data pour l'identifier.

Autorisations requises

Au minimum, les autorisations requises pour convertir un libellé en tag sont identiques à celles permettant de mettre à jour des libellés.

  • bigquery.datasets.update pour convertir un libellé d'ensemble de données
  • bigquery.tables.update pour convertir un libellé de table ou de vue

Les rôles Cloud IAM prédéfinis suivants incluent des autorisations bigquery.datasets.update :

  • bigquery.dataOwner
  • bigquery.admin

Les rôles Cloud IAM prédéfinis suivants incluent des autorisations bigquery.tables.update :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

En outre, si un utilisateur possède des autorisations bigquery.datasets.create, lorsqu'il crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. L'accès bigquery.dataOwner donne à l'utilisateur la possibilité de mettre à jour des libellés d'ensembles de données et les libellés des tables et vues qu'ils contiennent.

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

Convertir un libellé en tag

Pour convertir un libellé en tag, procédez comme suit :

Console

  1. Dans la console GCP, sélectionnez un ensemble de données, une table ou une vue.

  2. Pour les ensembles de données, la page des détails correspondante s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Details (Détails) pour ouvrir la page des détails.

    Détails de la table

  3. Sur la page des détails, cliquez sur l'icône en forme de crayon située à droite de Labels (Libellés).

    Icône en forme de crayon pour modifier un libellé

  4. Dans la boîte de dialogue Edilt labels (Modifier les libellés), effectuez les opérations suivantes :

    • Supprimez la valeur d'un libellé existant.
    • Cliquez sur Update (Mettre à jour).

UI classique

  1. Dans l'UI Web, sélectionnez la table ou la vue.

  2. Dans le cas des ensembles de données, la page Dataset Details (Détails de l'ensemble de données) s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Details (Détails) pour ouvrir la page des détails.

  3. Sur la page des détails, cliquez sur le bouton Edit (Modifier) à droite du champ Labels (Libellés).

  4. Dans la boîte de dialogue Edit Labels (Modifier les libellés), effectuez les opérations suivantes :

    • Supprimez la valeur d'un libellé existant.
    • Cliquez sur OK.

      Ajouter un tag

CLI

Pour convertir un libellé en tag, exécutez la commande bq update en saisissant l'indicateur set_label. Spécifiez la clé, suivie du caractère deux-points, mais ne renseignez pas la valeur. Cette action permet de transformer un libellé existant en tag.

bq update \
--set_label key: \
resource_id

Où :

  • key: est la clé de libellé que vous voulez convertir en tag.
  • resource_id est un nom valide d'ensemble de données, de table ou de vue. Si la ressource se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au format suivant : project_id:dataset.

Exemples :

Saisissez la commande ci-dessous pour transformer le libellé existant test_data:development de mydataset en tag. L'ensemble de données mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq update --set_label test_data: myotherproject:mydataset

Le résultat ressemble à ceci :

Dataset 'myotherproject:mydataset' successfully updated.

API

Pour convertir un libellé existant en tag, appelez la méthode datasets.patch ou tables.patch et remplacez les valeurs du libellé par la chaîne vide ("") dans la ressource d'ensemble de données ou la ressource de table.

Comme les vues sont traitées comme des ressources de table, la méthode tables.patch permet de modifier à la fois des vues et des tables. En outre, comme la méthode tables.update remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch.

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.