Using bucket labels

This page shows you how to add, view, edit, and remove the labels set on a bucket in Cloud Storage. For an overview of buckets and bucket labels, see the Key Terms.

Add a bucket label

Console

In the Google Cloud Console, go to the Cloud Storage Browser page.

Go to Browser
In the bucket list, find the bucket you want to apply a label to, and click its Bucket overflow menu ().
Click Edit labels.
In the side panel that appears, click the + Add label button.
Specify a key and value for your label.
Click Save.

In the Edit labels side panel, you can also edit the Value of existing labels.

To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.

gsutil

Use the -l flag in a label ch command. For example:

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

Where

KEY_1 is the key name for your label. For example, pet.
VALUE_1 is the value for your label. For example, dog.
BUCKET_NAME is the name of the bucket that the label applies to. For example, my-bucket.

Use multiple -l flags to add or edit multiple key:value pairs in a single command.

Use the label set command to replace all existing labels with new ones.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

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

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

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

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

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

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * 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

For more information, see the Cloud Storage PHP API reference documentation.

View on GitHub Feedback

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)
{
    // $bucketName = 'my-bucket';
    // $labelName = 'label-key-to-add';
    // $labelValue = 'label-value-to-add';

    $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

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

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

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

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

REST APIs

JSON API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
```
{
  "labels": {
    "KEY_1": "VALUE_1"
  }
}
```
Where
- KEY_1 is the key name for your label. For example, pet.
- VALUE_1 is the value for your label. For example, dog.
Use cURL to call the JSON API with a PATCH Bucket request:
```
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"
```
Where:
- JSON_FILE_NAME is the name of the JSON file you created in Step 2.
- OAUTH2_TOKEN is the access token you generated in Step 1.
- BUCKET_NAME is the name of the bucket that the label applies to. For example, my-bucket.

You can add or edit multiple key:value pairs in a request.

XML API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .xml file that contains the following information:
```
<Tagging>
  <TagSet>
    <Tag>
      <Key>KEY_1</Key>
      <Value>VALUE_1</Value>
    </Tag>
  </TagSet>
</Tagging>
```
Where:
- KEY_1 is the key name for your label. For example, pet.
- VALUE_1 is the value for your label. For example, dog.
Note that you can add multiple <Tag> elements in a request.
Use cURL to call the XML API with a PUT Bucket request and tagging query string parameter:
```
curl -X PUT --data-binary @XML_FILE_NAME.xml \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/BUCKET_NAME?tagging"
```
Where:
- XML_FILE_NAME is the XML file you created in Step 2.
- OAUTH2_TOKEN is the access token you generated in Step 1.
- BUCKET_NAME is the name of the bucket that the label applies to. For example, my-bucket.

View bucket labels

Console

In the Google Cloud Console, go to the Cloud Storage Browser page.

Go to Browser
(Optional): You can limit the columns displayed in the Cloud Console bucket list by clicking the Column display options menu ().
In the bucket list, find the bucket you want to verify, and check the entry for Label. You may need to scroll horizontally to view the Label column.

If your bucket has multiple labels, some may be hidden. When labels are hidden, an expandable button appears. Clicking the button displays all labels for a bucket.

To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.

gsutil

Use following gsutil ls command:

gsutil ls -L -b gs://BUCKET_NAME

Where:

BUCKET_NAME is the bucket whose labels you want to view. For example, my-bucket.

The response looks like the following example:

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