Getting Bucket Information

This page shows you how get information on the contents and metadata of your Cloud Storage buckets. For an overview of buckets, read the Key Terms. To learn more about specific bucket properties, see Storage Classes and Bucket Locations.

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.

  3. Optionally, use the Filter by prefix... field to narrow the results in your bucket list to objects with the prefix you specify.

    Filter by prefix textbox.

gsutil

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

gsutil ls -r 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]
...

Code samples

C#

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

The following sample lists all objects in a bucket:

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

The following sample lists objects with a given prefix:

private void ListObjects(string bucketName, string prefix,
    string delimiter)
{
    var storage = StorageClient.Create();
    var options = new ListObjectsOptions() { Delimiter = delimiter };
    foreach (var storageObject in storage.ListObjects(
        bucketName, prefix, options))
    {
        Console.WriteLine(storageObject.Name);
    }
}

Go

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

The following sample lists all objects in a bucket:

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

The following sample lists objects with a given prefix:

// Prefixes and delimiters can be used to emulate directory listings.
// Prefixes can be used filter objects starting with prefix.
// The delimiter argument can be used to restrict the results to only the
// objects in the given "directory". Without the delimeter, the entire  tree
// under the prefix is returned.
//
// For example, given these blobs:
//   /a/1.txt
//   /a/b/2.txt
//
// If you just specify prefix="a/", you'll get back:
//   /a/1.txt
//   /a/b/2.txt
//
// However, if you specify prefix="a/" and delim="/", you'll get back:
//   /a/1.txt
it := client.Bucket(bucket).Objects(ctx, &storage.Query{
	Prefix:    prefix,
	Delimiter: delim,
})
for {
	attrs, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintln(w, attrs.Name)
}

Java

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

The following sample lists all objects in a bucket:

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

The following sample lists objects with a given prefix:

Page<Blob> blobs = storage.list(bucketName, BlobListOption.currentDirectory(),
    BlobListOption.prefix(directory));
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.

The following sample lists all objects in a bucket:

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

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

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// 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);
  });

The following sample lists objects with a given prefix:

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

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const prefix = 'Prefix by which to filter, e.g. public/';
// const delimiter = 'Delimiter to use, e.g. /';

/**
 * This can be used to list all blobs in a "folder", e.g. "public/".
 *
 * The delimiter argument can be used to restrict the results to only the
 * "files" in the given "folder". Without the delimiter, the entire tree under
 * the prefix is returned. For example, given these blobs:
 *
 *   /a/1.txt
 *   /a/b/2.txt
 *
 * If you just specify prefix = '/a', you'll get back:
 *
 *   /a/1.txt
 *   /a/b/2.txt
 *
 * However, if you specify prefix='/a' and delimiter='/', you'll get back:
 *
 *   /a/1.txt
 */
const options = {
  prefix: prefix,
};

if (delimiter) {
  options.delimiter = delimiter;
}

// Lists files in the bucket, filtered by a prefix
storage
  .bucket(bucketName)
  .getFiles(options)
  .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.

The following sample lists all objects in a bucket:

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());
    }
}

The following sample lists objects with a given prefix:

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_with_prefix($bucketName, $prefix)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $options = ['prefix' => $prefix];
    foreach ($bucket->objects($options) 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.

The following sample lists all objects in a bucket:

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)

The following sample lists objects with a given prefix:

def list_blobs_with_prefix(bucket_name, prefix, delimiter=None):
    """Lists all the blobs in the bucket that begin with the prefix.

    This can be used to list all blobs in a "folder", e.g. "public/".

    The delimiter argument can be used to restrict the results to only the
    "files" in the given "folder". Without the delimiter, the entire tree under
    the prefix is returned. For example, given these blobs:

        /a/1.txt
        /a/b/2.txt

    If you just specify prefix = '/a', you'll get back:

        /a/1.txt
        /a/b/2.txt

    However, if you specify prefix='/a' and delimiter='/', you'll get back:

        /a/1.txt

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

    blobs = bucket.list_blobs(prefix=prefix, delimiter=delimiter)

    print('Blobs:')
    for blob in blobs:
        print(blob.name)

    if delimiter:
        print('Prefixes:')
        for prefix in blobs.prefixes:
            print(prefix)

Ruby

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

The following sample lists all objects in a bucket:

# 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

The following sample lists objects with a given prefix:

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
# prefix      = "Filter results to files whose names begin with this prefix"

require "google/cloud/storage"

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

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"

    You can use a prefix=[PREFIX] query string parameter to limit results to objects that have the specified prefix.

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]"

    You can use a prefix=[PREFIX] query string parameter to limit results to objects that have the specified prefix.

See the List Objects XML reference page for more information.

Determining a bucket's size

To get the size of a bucket, use the gsutil command line tool. Specifically, use the gsutil du command with a -s flag:

gsutil du -s gs://[BUCKET_NAME]/

where [BUCKET_NAME] is the name of the desired bucket.

The response looks like the following example:

134620      gs://[BUCKET_NAME]

In this example, the size of the bucket is 134,620 bytes.

Displaying a bucket's location and default storage class

To display the geographic location and default storage class 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, find the bucket you want to verify, and check its Location and Default storage class.

    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
  ...

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"

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.
    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>

What's next

Send feedback about...

Cloud Storage Documentation