Utiliser les étiquettes de buckets

Cette page vous explique comment ajouter, afficher, modifier et supprimer les libellés définis sur un bucket dans Cloud Storage. Pour une présentation des buckets et des libellés, consultez la page Termes clés.

Ajouter un libellé de bucket

Console

  1. Dans Google Cloud Console, accédez à la page du Navigateur Cloud Storage.

    Accéder à la page du navigateur

  2. Dans la liste des buckets, localisez le bucket auquel appliquer le libellé, puis cliquez sur le menu à développer du bucket ().

  3. Cliquez sur Modifier les libellés.

  4. Dans le panneau latéral qui apparaît, cliquez sur le bouton Ajouter un libellé.

  5. Spécifiez les éléments key et value associés au libellé.

  6. Cliquez sur Enregistrer.

Dans le panneau latéral Modifier les libellés, vous pouvez également modifier la valeur des libellés existants.

Pour savoir comment obtenir des informations d'erreur détaillées sur les opérations ayant échoué dans le navigateur Cloud Storage, consultez la page Dépannage.

gsutil

Utilisez l'option -l dans une commande label ch. Exemple :

gsutil label ch -l KEY_1:VALUE_1 gs://BUCKET_NAME

  • KEY_1 est le nom de clé du libellé. Exemple : pet.
  • VALUE_1 est la valeur du libellé. Exemple : dog.
  • BUCKET_NAME est le nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Utilisez plusieurs options -l pour ajouter ou modifier plusieurs paires key:value dans une seule commande.

Exécutez la commande label set pour remplacer tous les libellés existants par de nouveaux.

Exemples de code

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& label_key, std::string const& label_value) {
  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetLabel(label_key, label_value));

  if (!updated_metadata) {
    throw std::runtime_error(updated_metadata.status().message());
  }

  std::cout << "Successfully set label " << label_key << " to " << label_value
            << " on bucket  " << updated_metadata->name() << ".";
  std::cout << " The bucket labels are now:";
  for (auto const& kv : updated_metadata->labels()) {
    std::cout << "\n  " << kv.first << ": " << kv.second;
  }
  std::cout << "\n";
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

import (
	"context"
	"fmt"
	"io"
	"time"

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

// addBucketLabel adds a label on a bucket.
func addBucketLabel(w io.Writer, bucketName, labelName, labelValue string) error {
	// bucketName := "bucket-name"
	// labelName := "label-name"
	// labelValue := "label-value"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{}
	bucketAttrsToUpdate.SetLabel(labelName, labelValue)
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Added label %q with value %q to bucket %v\n", labelName, labelValue, bucketName)
	return nil
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class AddBucketLabel {
  public static void addBucketLabel(
      String projectId, String bucketName, String labelKey, String labelValue) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The key of the label to add
    // String labelKey = "label-key-to-add";

    // The value of the label to add
    // String labelValue = "label-value-to-add";

    Map<String, String> labelsToAdd = new HashMap<>();
    labelsToAdd.put(labelKey, labelValue);

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    Map<String, String> labels = bucket.getLabels();
    if (labels == null) {
      labels = labelsToAdd;
    } else {
      labels.putAll(labelsToAdd);
    }
    bucket.toBuilder().setLabels(labels).build().update();

    System.out.println(
        "Added label " + labelKey + " with value " + labelValue + " to bucket " + bucketName + ".");
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The key of the label to add
// const labelKey = 'label-key-to-add';

// The value of the label to add
// const labelValue = 'label-value-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

const labels = {
  [labelKey]: labelValue,
};

async function addBucketLabel() {
  await storage.bucket(bucketName).setLabels(labels);
  console.log(`Added label to bucket ${bucketName}`);
}

addBucketLabel().catch(console.error);

PHP

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Adds or updates a bucket label.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $labelName the name of the label to add.
 * @param string $labelValue the value of the label to add.
 */
function add_bucket_label($bucketName, $labelName, $labelValue)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $newLabels = [$labelName => $labelValue];
    $bucket->update(['labels' => $newLabels]);
    printf('Added label %s (%s) to %s' . PHP_EOL, $labelName, $labelValue, $bucketName);
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

import pprint

from google.cloud import storage

def add_bucket_label(bucket_name):
    """Add a label to a bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    labels = bucket.labels
    labels["example"] = "label"
    bucket.labels = labels
    bucket.patch()

    print("Updated labels on {}.".format(bucket.name))
    pprint.pprint(bucket.labels)

Ruby

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

def add_bucket_label bucket_name:, label_key:, label_value:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The key of the label to add
  # label_key = "label-key-to-add"

  # The value of the label to add
  # label_value = "label-value-to-add"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  bucket.update do |bucket|
    bucket.labels[label_key] = label_value
  end

  puts "Added label #{label_key} with value #{label_value} to #{bucket_name}"
end

API REST

API JSON

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Créez un fichier .json contenant les informations suivantes :

    {
      "labels": {
        "KEY_1": "VALUE_1"
      }
    }

    • KEY_1 est le nom de clé du libellé. Exemple : pet.
    • VALUE_1 est la valeur du libellé. Exemple : dog.
  3. Exécutez cURL pour appeler l'API JSON avec une requête de bucket PATCH :

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      -H "Content-Type: application/json" \
      "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"

    Où :

    • JSON_FILE_NAME correspond au nom du fichier JSON que vous avez créé à l'étape 2 ;
    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME est le nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Vous pouvez ajouter ou modifier plusieurs paires key:value dans une requête.

API XML

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Créez un fichier .xml contenant les informations suivantes :

    <Tagging>
      <TagSet>
        <Tag>
          <Key>KEY_1</Key>
          <Value>VALUE_1</Value>
        </Tag>
      </TagSet>
    </Tagging>

    Où :

    • KEY_1 est le nom de clé du libellé. Exemple : pet.
    • VALUE_1 est la valeur du libellé. Exemple : dog.

    Notez que vous pouvez ajouter plusieurs éléments <Tag> dans une requête.

  3. Utilisez cURL pour appeler l'API XML avec une requête de bucket PUT et le paramètre de chaîne de requête tagging :

    curl -X PUT --data-binary @XML_FILE_NAME.xml \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      "https://storage.googleapis.com/BUCKET_NAME?tagging"

    Où :

    • XML_FILE_NAME correspond au fichier XML que vous avez créé à l'étape 2 ;
    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME est le nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Afficher les libellés de buckets

Console

  1. Dans Google Cloud Console, accédez à la page du Navigateur Cloud Storage.

    Accéder à la page du navigateur

  2. (Facultatif) : vous pouvez limiter le nombre de colonnes affichées dans la liste des buckets Cloud Console en cliquant sur le menu des options d'affichage des colonnes (Icône d&#39;options de colonnes.).

  3. Dans la liste des buckets, recherchez le bucket que vous souhaitez vérifier et consultez l'entrée qui existe pour Labels (Libellés). Vous devrez peut-être faire défiler la page horizontalement pour afficher la colonne Labels (Libellés).

    Si votre bucket comporte plusieurs libellés, certains pourraient être masqués. Dans ce cas précis, une flèche vers le bas apparaît. Cliquez sur le bouton pour afficher tous les libellés d'un bucket.

    Liste des buckets avec colonne des libellés

Pour savoir comment obtenir des informations d'erreur détaillées sur les opérations ayant échoué dans le navigateur Cloud Storage, consultez la page Dépannage.

gsutil

Exécutez la commande gsutil ls suivante :

gsutil ls -L -b gs://BUCKET_NAME

Où :

  • BUCKET_NAME correspond au bucket dont vous souhaitez afficher les libellés. Exemple : my-bucket.

La réponse est semblable à ceci :

gs://my-bucket/ :
  Storage class:         STANDARD
  ...
  ...
  Labels:
    {
      "your_label_key": "your_label_value"
    }
  ...

Exemples de code

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.GetBucketMetadata(bucket_name, gcs::Fields("labels"));

  if (!bucket_metadata) {
    throw std::runtime_error(bucket_metadata.status().message());
  }

  if (bucket_metadata->labels().empty()) {
    std::cout << "The bucket " << bucket_name << " has no labels set.\n";
    return;
  }

  std::cout << "The labels for bucket " << bucket_name << " are:";
  for (auto const& kv : bucket_metadata->labels()) {
    std::cout << "\n  " << kv.first << ": " << kv.second;
  }
  std::cout << "\n";
}

PHP

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Prints a list of a bucket's lables.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function get_bucket_labels($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();
    if (isset($info['labels'])) {
        foreach ($info['labels'] as $labelKey => $labelValue) {
            printf('%s: %s' . PHP_EOL, $labelKey, $labelValue);
        }
    }
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

import pprint

from google.cloud import storage

def get_bucket_labels(bucket_name):
    """Prints out a bucket's labels."""
    # bucket_name = 'your-bucket-name'
    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)

    labels = bucket.labels
    pprint.pprint(labels)

API REST

API JSON

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Utilisez cURL pour appeler l'API JSON avec une requête de bucket GET incluant le paramètre de chaîne de requête fields=labels :

    curl -X GET \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"

    Où :

    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME correspond au nom du bucket dont vous souhaitez afficher les libellés. Exemple : my-bucket.

La réponse est semblable à ceci :

{
  "labels" : {
     (your_label_key): your_label_value
   },
}

API XML

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Utilisez cURL pour appeler l'API XML avec une requête de bucket GET et le paramètre de chaîne de requête tagging :

    curl -X GET \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      "https://storage.googleapis.com/BUCKET_NAME?tagging"

    Où :

    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME correspond au nom du bucket dont vous souhaitez afficher les libellés. Exemple : my-bucket.

La réponse est semblable à ceci :

<Tagging>
  <TagSet>
    <Tag>
      <Key>your_label_key</Key>
      <Value>your_label_value</Value>
    </Tag>
  </TagSet>
</Tagging>

Supprimer un libellé de bucket

Console

  1. Dans Google Cloud Console, accédez à la page du Navigateur Cloud Storage.

    Accéder à la page du navigateur

  2. Dans la liste des buckets, recherchez le bucket dont vous souhaitez supprimer le libellé, puis cliquez sur le menu à développer du bucket ().

  3. Cliquez sur Modifier les libellés.

  4. Cliquez sur le signe X à côté de chaque libellé que vous souhaitez supprimer.

  5. Cliquez sur Enregistrer.

Pour savoir comment obtenir des informations d'erreur détaillées sur les opérations ayant échoué dans le navigateur Cloud Storage, consultez la page Dépannage.

gsutil

Utilisez l'option -d dans une commande label ch. Exemple :

gsutil label ch -d KEY_1 gs://BUCKET_NAME

Où :

  • KEY_1 est le nom de clé du libellé. Exemple : pet.
  • BUCKET_NAME est le nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Exécutez la commande label set pour remplacer tous les libellés existants par de nouveaux.

Exemples de code

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& label_key) {
  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().ResetLabel(label_key));

  if (!updated_metadata) {
    throw std::runtime_error(updated_metadata.status().message());
  }

  std::cout << "Successfully reset label " << label_key << " on bucket  "
            << updated_metadata->name() << ".";
  if (updated_metadata->labels().empty()) {
    std::cout << " The bucket now has no labels.\n";
    return;
  }
  std::cout << " The bucket labels are now:";
  for (auto const& kv : updated_metadata->labels()) {
    std::cout << "\n  " << kv.first << ": " << kv.second;
  }
  std::cout << "\n";
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

import (
	"context"
	"fmt"
	"io"
	"time"

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

// removeBucketLabel removes a label on a bucket.
func removeBucketLabel(w io.Writer, bucketName, labelName string) error {
	// bucketName := "bucket-name"
	// labelName := "label-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{}
	bucketAttrsToUpdate.DeleteLabel(labelName)
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Removed label %q from bucket %v\n", labelName, bucketName)
	return nil
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class RemoveBucketLabel {
  public static void removeBucketLabel(String projectId, String bucketName, String labelKey) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The key of the label to remove from the bucket
    // String labelKey = "label-key-to-remove";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Map<String, String> labelsToRemove = new HashMap<>();
    labelsToRemove.put(labelKey, null);

    Bucket bucket = storage.get(bucketName);
    Map<String, String> labels;
    if (bucket.getLabels() == null) {
      labels = new HashMap<>();
    } else {
      labels = new HashMap(bucket.getLabels());
    }
    labels.putAll(labelsToRemove);
    bucket.toBuilder().setLabels(labels).build().update();

    System.out.println("Removed label " + labelKey + " from bucket " + bucketName);
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The key of the label to remove from the bucket
// const labelKey = 'label-key-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeBucketLabel() {
  await storage.bucket(bucketName).deleteLabels(labelKey);
  console.log(`Removed labels from bucket ${bucketName}`);
}

removeBucketLabel().catch(console.error);

PHP

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Removes a label from a bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $labelName the name of the label to remove.
 */
function remove_bucket_label($bucketName, $labelName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $labels = [$labelName => null];
    $bucket->update(['labels' => $labels]);
    printf('Removed label %s from %s' . PHP_EOL, $labelName, $bucketName);
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

import pprint

from google.cloud import storage

def remove_bucket_label(bucket_name):
    """Remove a label from a bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    labels = bucket.labels

    if "example" in labels:
        del labels["example"]

    bucket.labels = labels
    bucket.patch()

    print("Removed labels on {}.".format(bucket.name))
    pprint.pprint(bucket.labels)

Ruby

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

def remove_bucket_label bucket_name:, label_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The key of the label to remove from the bucket
  # label_key = "label-key-to-remove"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  bucket.update do |bucket|
    bucket.labels[label_key] = nil
  end

  puts "Deleted label #{label_key} from #{bucket_name}"
end

API REST

API JSON

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Créez un fichier .json contenant les informations suivantes :

    {
      "labels": {
        "KEY_1": null
      }
    }

    Où :

    • KEY_1 est le nom de clé du libellé. Exemple : pet.
  3. Exécutez cURL pour appeler l'API JSON avec une requête de bucket PATCH :

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      -H "Content-Type: application/json" \
      "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"

    Où :

    • JSON_FILE_NAME correspond au nom du fichier JSON que vous avez créé à l'étape 2 ;
    • OAUTH2_TOKEN correspond au nom du jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME correspond au nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Vous pouvez supprimer plusieurs paires key:value dans une requête.

API XML

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth.
  2. Créez un fichier .xml contenant les informations suivantes :

    <Tagging>
      <TagSet>
        <Tag>
        </Tag>
      </TagSet>
    </Tagging>

    Notez que vous pouvez ajouter plusieurs éléments <Tag> dans une requête.

  3. Utilisez cURL pour appeler l'API XML avec une requête de bucket PUT et le paramètre de chaîne de requête tagging :

    curl -X PUT --data-binary @XML_FILE_NAME.xml \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      "https://storage.googleapis.com/BUCKET_NAME?tagging"

    Où :

    • XML_FILE_NAME correspond au nom du fichier XML que vous avez créé à l'étape 2 ;
    • OAUTH2_TOKEN correspond au nom du jeton d'accès que vous avez généré à l'étape 1 ;
    • BUCKET_NAME correspond au nom du bucket auquel le libellé s'applique. Exemple : my-bucket.

Étapes suivantes