Managing Buckets

This page shows you how to manage your Cloud Storage buckets. For an overview of buckets, read the Key Terms. To learn more about specific bucket properties, see Storage Classes, Bucket Locations, and Bucket Labels. To move or rename a bucket, see Moving and Renaming Buckets.

Listing a bucket's contents

To list the contents of a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the bucket list, select the bucket whose contents you want to view.

gsutil

Use the gsutil ls command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil ls gs://[BUCKET_NAME]/**

The response looks like the following example:

gs://[BUCKET_NAME]/[OBJECT_NAME1]
gs://[BUCKET_NAME]/[OBJECT_NAME2]
gs://[BUCKET_NAME]/[OBJECT_NAME3]
...

Client libraries

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

private void ListObjects(string bucketName)
{
    var storage = StorageClient.Create();
    foreach (var bucket in storage.ListObjects(bucketName, ""))
    {
        Console.WriteLine(bucket.Name);
    }
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

it := client.Bucket(bucket).Objects(ctx, nil)
for {
	attrs, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(attrs.Name)
}

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

Page<Blob> blobs = bucket.list();
for (Blob blob : blobs.iterateAll()) {
  // do something with the blob
}

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

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

// The name of the bucket to access, e.g. "my-bucket"
// const bucketName = "my-bucket";

// Instantiates a client
const storage = Storage();

// Lists files in the bucket
storage
  .bucket(bucketName)
  .getFiles()
  .then((results) => {
    const files = results[0];

    console.log('Files:');
    files.forEach((file) => {
      console.log(file.name);
    });
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Add ACL to a Cloud Storage Bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 *
 * @return void
 */
function list_objects($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    foreach ($bucket->objects() as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def list_blobs(bucket_name):
    """Lists all the blobs in the bucket."""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    blobs = bucket.list_blobs()

    for blob in blobs:
        print(blob.name)

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"

require "google/cloud/storage"

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

bucket.files.each do |file|
  puts file.name
end

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o"

See the Objects: list JSON reference page for more information.

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]"

See the List Objects XML reference page for more information.

Displaying a bucket's properties

To display the default storage class of a bucket, the geographic location of the bucket, and the labels applied to a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the bucket list, find the bucket you want to verify, and check its Default storage class, Location, and Label values.

    Verify Multi-Regional Storage bucket class.

gsutil

Use following gsutil ls command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil ls -L -b gs://[BUCKET_NAME]/

The response looks like the following example:

gs://[BUCKET_NAME]/ :
  Storage class:         MULTI_REGIONAL
  Location constraint:   US
  ...
  ...
  Labels:
    {
      "your_label_key": "your_label_value"
    }
  ...

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API with a GET Bucket request that includes the desired fields, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=location%2CstorageClass%2Clabels"

The response looks like the following example:

{
  "location": "US",
  "storageClass": "MULTI_REGIONAL"
  "labels" : {
     (YOUR_LABEL_KEY): YOUR_LABEL_VALUE
   },
}

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API with a GET Bucket request that includes the desired query string parameter:
    • location for getting the location of the bucket.
    • storageClass for getting the default storage class of the bucket.
    • tagging for getting the labels applied to the bucket.
    Note that you can use only one such query parameter at a time with the XML API. For example, to get the location of a bucket, use the following command, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?location"

The response looks like the following example:

<LocationConstraint>US</LocationConstraint>

Managing a bucket's default storage class

To change the default storage class of an existing bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the bucket list, find the bucket you want to modify, and click its more options button (three vertical dots).

  3. Click Edit default storage class.

  4. In the overlay window, select the new default storage class you would like for your bucket.

    Note that based on the location of your bucket, not all storage classes are available.

    Edit bucket storage class.

  5. Click Save.

gsutil

Use the gsutil defstorageclass set command with the desired storage class, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil defstorageclass set [STORAGE_CLASS] gs://[BUCKET_NAME]

The response looks like the following example:

Setting default storage class to "[STORAGE_CLASS]" for bucket gs://[BUCKET_NAME]

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. {
      "storageClass": "[STORAGE_CLASS]"
    }
  4. Use cURL to call the JSON API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=storageClass"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .xml file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. <StorageClass>[STORAGE_CLASS]</StorageClass>
  4. Use cURL to call the XML API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?storageClass"

Managing a bucket's labels

To add, edit or delete the labels applied to a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. Select the checkbox of the bucket whose labels you wish to manage.

  3. In the side panel that appears, click the Labels tab.

  4. Manage the bucket labels as desired.

    1. To add a label, click the + Add label button and specify a new key:value pair.

    2. To modify a label, edit the desired text box in the Value column. Note that you should create a new label if you want to change the Key.

    3. To delete a label, click the X associated with it.

  5. Click Save.

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, [VALUE_1] is the value for your label and [BUCKET_NAME] is the name of the bucket that the label applies to.

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

  • Use the -d flag to delete labels that have the specified keys.

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

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. {
      "labels": {
        "[KEY_1]": "[VALUE_1]"
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=labels"

You can add/edit multiple key:value pairs in a request, and to delete a label, set its value to null. For example:

{
  "labels": {
    "New_Label_Key": "New_Label_Value",
    "Existing_Label_Key": "Updated_Label_Value",
    "Old_Label_Key": null
  }
}

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .xml file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <Tagging>
      <TagSet>
        <Tag>
          <Key>[KEY_1]</Key>
          <Value>[VALUE_1]</Value>
        </Tag>
      </TagSet>
    </Tagging>

    Note that you can add multiple <Tag> elements in a request.

  3. Use cURL to call the XML API, with a PUT Bucket request and tagging query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?tagging"

Deleting a bucket

To delete a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. Select the checkbox of the bucket you want to delete.

  3. Click Delete.

  4. In the overlay window that appears, confirm you want to delete the bucket and its contents by clicking Delete.

gsutil

Use the gsutil rm command with the -r flag, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil rm -r gs://[BUCKET_NAME]

The response looks like the following example:

Removing gs://[BUCKET_NAME]/...

Client libraries

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

private void DeleteBucket(string bucketName)
{
    var storage = StorageClient.Create();
    storage.DeleteBucket(bucketName);
    Console.WriteLine($"Deleted {bucketName}.");
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

if err := client.Bucket(bucketName).Delete(ctx); err != nil {
	return err
}

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

boolean deleted = bucket.delete(BucketSourceOption.metagenerationMatch());
if (deleted) {
  // the bucket was deleted
} else {
  // the bucket was not found
}

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

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

// The name of the bucket to delete, e.g. "my-bucket"
// const bucketName = "my-bucket";

// Instantiates a client
const storage = Storage();

// Deletes the bucket
storage
  .bucket(bucketName)
  .delete()
  .then(() => {
    console.log(`Bucket ${bucketName} deleted.`);
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Delete a Cloud Storage Bucket.
 *
 * @param string $bucketName the name of the bucket to delete.
 *
 * @return void
 */
function delete_bucket($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->delete();
    printf('Bucket deleted: %s' . PHP_EOL, $bucket->name());
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def delete_bucket(bucket_name):
    """Deletes a bucket. The bucket must be empty."""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    bucket.delete()
    print('Bucket {} deleted'.format(bucket.name))

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket to delete"

require "google/cloud/storage"

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

bucket.delete

puts "Deleted bucket: #{bucket.name}"

REST APIs

JSON API

Note that your bucket must be empty before you can delete it.

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X DELETE -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]"

If successful, the response contains a 204 status code.

See the Buckets: delete JSON reference page for more information.

XML API

Note that your bucket must be empty before you can delete it.

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X DELETE -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]"

See the Delete Bucket XML reference page for more information.

Preventing caching

To improve performance, data may be temporarily cached by Google systems when data is being written to or read from a bucket. Here are some ways you can prevent such delivery-based caching:

  • Proxy data transfers through a Google App Engine application located in the same location as your bucket

  • Use appropriate cache-control headers for your Cloud Storage objects to specify that they not be cached in edge-caches.

    For example, use the response header Cache-Control: no-cache for an object to specify that the object must not be used to satisfy a subsequent request. For more information about cache-control directives, see RFC 7234: Cache-Control.

Send feedback about...

Cloud Storage Documentation