Get bucket metadata
This page shows you how get information on the metadata of your Cloud Storage buckets, excluding IAM policies and ACLs.
To learn how to get the IAM policy of your bucket, see View the IAM policy for a bucket.
Required roles
In order to get the required permissions for getting the metadata of a
Cloud Storage bucket, ask your administrator to grant you the Storage
Admin (roles/storage.admin) role on the bucket.
This role contains the permissions required to get the metadata of a bucket. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
storage.buckets.getstorage.buckets.list- This permission is only needed if you plan on using the Google Cloud console to perform the task on this page.
You might also be able to get these permissions with other predefined roles or custom roles.
For instructions on granting roles on buckets, see Set and manage IAM policies on buckets.
Display a bucket's metadata
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the bucket list, click the name of the bucket whose metadata you want to view.
Click the Configuration tab to view bucket details such as the included regions, storage class, permissions, and replication type.
Command line
Use the gcloud storage buckets describe command:
gcloud storage buckets describe gs://BUCKET_NAME
Where:
BUCKET_NAMEis the name of the bucket whose metadata you want to view. For example,my-awesome-bucket.
If successful, the response looks similar to the following example:
defaultEventBasedHold: false etag: CAE= iamConfiguration: bucketPolicyOnly: enabled: true ...
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for client libraries.
C++
namespacegcs=::google::cloud::storage;
using::google::cloud::StatusOr;
[](gcs::Clientclient,std::stringconst&bucket_name){
StatusOr<gcs::BucketMetadata>bucket_metadata=
client.GetBucketMetadata(bucket_name);
if(!bucket_metadata)throwstd::move(bucket_metadata).status();
std::cout << "The metadata for bucket " << bucket_metadata->name() << " is "
<< *bucket_metadata << "\n";
}C#
usingGoogle.Apis.Storage.v1.Data;
usingGoogle.Cloud.Storage.V1 ;
usingSystem;
publicclassGetBucketMetadataSample
{
publicBucketGetBucketMetadata(stringbucketName="your-unique-bucket-name")
{
varstorage=StorageClient .Create ();
varbucket=storage.GetBucket(bucketName,newGetBucketOptions {Projection=Projection .Full });
Console.WriteLine($"Bucket:\t{bucket.Name}");
Console.WriteLine($"Acl:\t{bucket.Acl}");
Console.WriteLine($"Billing:\t{bucket.Billing}");
Console.WriteLine($"Cors:\t{bucket.Cors}");
Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
Console.WriteLine($"Encryption:\t{bucket.Encryption}");
if(bucket.Encryption!=null)
{
Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
}
Console.WriteLine($"Id:\t{bucket.Id}");
Console.WriteLine($"Kind:\t{bucket.Kind}");
Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
Console.WriteLine($"Location:\t{bucket.Location}");
Console.WriteLine($"LocationType:\t{bucket.LocationType}");
Console.WriteLine($"Logging:\t{bucket.Logging}");
Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
Console.WriteLine($"ObjectRetention:\t{bucket.ObjectRetention}");
Console.WriteLine($"Owner:\t{bucket.Owner}");
Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
Console.WriteLine($"Updated:\t{bucket.Updated}");
Console.WriteLine($"Versioning:\t{bucket.Versioning}");
Console.WriteLine($"Website:\t{bucket.Website}");
Console.WriteLine($"TurboReplication:\t{bucket.Rpo}");
if(bucket.Labels!=null)
{
Console.WriteLine("Labels:");
foreach(varlabelinbucket.Labels)
{
Console.WriteLine($"{label.Key}:\t{label.Value}");
}
}
returnbucket;
}
}Go
import(
"context"
"fmt"
"io"
"time"
"cloud.google.com/go/storage"
)
// getBucketMetadata gets the bucket metadata.
funcgetBucketMetadata(wio.Writer ,bucketNamestring)(*storage.BucketAttrs ,error){
// bucketName := "bucket-name"
ctx:=context.Background()
client,err:=storage.NewClient(ctx)
iferr!=nil{
returnnil,fmt.Errorf("storage.NewClient: %w",err)
}
deferclient.Close()
ctx,cancel:=context.WithTimeout(ctx,time.Second*10)
defercancel()
attrs,err:=client.Bucket (bucketName).Attrs(ctx)
iferr!=nil{
returnnil,fmt.Errorf("Bucket(%q).Attrs: %w",bucketName,err)
}
fmt.Fprintf(w,"BucketName: %v\n",attrs.Name)
fmt.Fprintf(w,"Location: %v\n",attrs.Location)
fmt.Fprintf(w,"LocationType: %v\n",attrs.LocationType)
fmt.Fprintf(w,"StorageClass: %v\n",attrs.StorageClass)
fmt.Fprintf(w,"Turbo replication (RPO): %v\n",attrs.RPO )
fmt.Fprintf(w,"TimeCreated: %v\n",attrs.Created)
fmt.Fprintf(w,"Metageneration: %v\n",attrs.MetaGeneration)
fmt.Fprintf(w,"PredefinedACL: %v\n",attrs.PredefinedACL)
ifattrs.Encryption!=nil{
fmt.Fprintf(w,"DefaultKmsKeyName: %v\n",attrs.Encryption.DefaultKMSKeyName)
}
ifattrs.Website!=nil{
fmt.Fprintf(w,"IndexPage: %v\n",attrs.Website.MainPageSuffix)
fmt.Fprintf(w,"NotFoundPage: %v\n",attrs.Website.NotFoundPage)
}
fmt.Fprintf(w,"DefaultEventBasedHold: %v\n",attrs.DefaultEventBasedHold)
ifattrs.RetentionPolicy !=nil{
fmt.Fprintf(w,"RetentionEffectiveTime: %v\n",attrs.RetentionPolicy .EffectiveTime)
fmt.Fprintf(w,"RetentionPeriod: %v\n",attrs.RetentionPolicy .RetentionPeriod)
fmt.Fprintf(w,"RetentionPolicyIsLocked: %v\n",attrs.RetentionPolicy .IsLocked)
}
fmt.Fprintf(w,"ObjectRetentionMode: %v\n",attrs.ObjectRetentionMode)
fmt.Fprintf(w,"RequesterPays: %v\n",attrs.RequesterPays)
fmt.Fprintf(w,"VersioningEnabled: %v\n",attrs.VersioningEnabled)
ifattrs.Logging!=nil{
fmt.Fprintf(w,"LogBucket: %v\n",attrs.Logging.LogBucket)
fmt.Fprintf(w,"LogObjectPrefix: %v\n",attrs.Logging.LogObjectPrefix)
}
ifattrs.CORS !=nil{
fmt.Fprintln(w,"CORS:")
for_,v:=rangeattrs.CORS {
fmt.Fprintf(w,"\tMaxAge: %v\n",v.MaxAge)
fmt.Fprintf(w,"\tMethods: %v\n",v.Methods)
fmt.Fprintf(w,"\tOrigins: %v\n",v.Origins)
fmt.Fprintf(w,"\tResponseHeaders: %v\n",v.ResponseHeaders)
}
}
ifattrs.Labels!=nil{
fmt.Fprintf(w,"\n\n\nLabels:")
forkey,value:=rangeattrs.Labels{
fmt.Fprintf(w,"\t%v = %v\n",key,value)
}
}
returnattrs,nil
}
Java
importcom.google.cloud.storage.Bucket ;
importcom.google.cloud.storage.BucketInfo ;
importcom.google.cloud.storage.Storage ;
importcom.google.cloud.storage.StorageOptions ;
importjava.util.Map;
publicclass GetBucketMetadata{
publicstaticvoidgetBucketMetadata(StringprojectId,StringbucketName){
// The ID of your GCP project
// String projectId = "your-project-id";
// The ID of your GCS bucket
// String bucketName = "your-unique-bucket-name";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
// Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
Bucket bucket=
storage.get (bucketName,Storage.BucketGetOption.fields(Storage.BucketField.values()));
// Print bucket metadata
System.out.println("BucketName: "+bucket.getName());
System.out.println("DefaultEventBasedHold: "+bucket.getDefaultEventBasedHold ());
System.out.println("DefaultKmsKeyName: "+bucket.getDefaultKmsKeyName ());
System.out.println("Id: "+bucket.getGeneratedId());
System.out.println("IndexPage: "+bucket.getIndexPage ());
System.out.println("Location: "+bucket.getLocation());
System.out.println("LocationType: "+bucket.getLocationType ());
System.out.println("Metageneration: "+bucket.getMetageneration());
System.out.println("NotFoundPage: "+bucket.getNotFoundPage ());
System.out.println("RetentionEffectiveTime: "+bucket.getRetentionEffectiveTime ());
System.out.println("RetentionPeriod: "+bucket.getRetentionPeriod ());
System.out.println("RetentionPolicyIsLocked: "+bucket.retentionPolicyIsLocked ());
System.out.println("RequesterPays: "+bucket.requesterPays());
System.out.println("SelfLink: "+bucket.getSelfLink());
System.out.println("StorageClass: "+bucket.getStorageClass().name ());
System.out.println("TimeCreated: "+bucket.getCreateTime());
System.out.println("VersioningEnabled: "+bucket.versioningEnabled ());
System.out.println("ObjectRetention: "+bucket.getObjectRetention ());
if(bucket.getLabels()!=null){
System.out.println("\n\n\nLabels:");
for(Map.Entry<String,String>label:bucket.getLabels().entrySet()){
System.out.println(label.getKey()+"="+label.getValue());
}
}
if(bucket.getLifecycleRules()!=null){
System.out.println("\n\n\nLifecycle Rules:");
for(BucketInfo.LifecycleRulerule:bucket.getLifecycleRules()){
System.out.println(rule);
}
}
}
}Node.js
// Imports the Google Cloud client library
const{Storage}=require('@google-cloud/storage');
// Creates a client
conststorage=newStorage();
asyncfunctiongetBucketMetadata(){
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';
// Get Bucket Metadata
const[metadata]=awaitstorage.bucket(bucketName).getMetadata();
console.log(JSON .stringify(metadata,null,2));
}PHP
use Google\Cloud\Storage\StorageClient;
/**
* Get bucket metadata.
*
* @param string $bucketName The name of your Cloud Storage bucket.
* (e.g. 'my-bucket')
*/
function get_bucket_metadata(string $bucketName): void
{
$storage = new StorageClient();
$bucket = $storage->bucket($bucketName);
$info = $bucket->info();
printf('Bucket Metadata: %s' . PHP_EOL, print_r($info, true));
}Python
fromgoogle.cloudimport storage
defbucket_metadata(bucket_name):
"""Prints out a bucket's metadata."""
# bucket_name = 'your-bucket-name'
storage_client = storage .Client ()
bucket = storage_client.get_bucket (bucket_name)
print(f"ID: {bucket.id}")
print(f"Name: {bucket.name}")
print(f"Storage Class: {bucket.storage_class}")
print(f"Location: {bucket.location }")
print(f"Location Type: {bucket.location_type }")
print(f"Cors: {bucket.cors }")
print(f"Default Event Based Hold: {bucket.default_event_based_hold }")
print(f"Default KMS Key Name: {bucket.default_kms_key_name }")
print(f"Metageneration: {bucket.metageneration}")
print(
f"Public Access Prevention: {bucket.iam_configuration .public_access_prevention }"
)
print(f"Retention Effective Time: {bucket.retention_policy_effective_time }")
print(f"Retention Period: {bucket.retention_period }")
print(f"Retention Policy Locked: {bucket.retention_policy_locked }")
print(f"Object Retention Mode: {bucket.object_retention_mode }")
print(f"Requester Pays: {bucket.requester_pays }")
print(f"Self Link: {bucket.self_link}")
print(f"Time Created: {bucket.time_created}")
print(f"Versioning Enabled: {bucket.versioning_enabled }")
print(f"Labels: {bucket.labels }")
Ruby
defget_bucket_metadatabucket_name:
# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
require"google/cloud/storage"
storage=Google::Cloud::Storage .new
bucket=storage.bucketbucket_name
puts"ID: #{bucket.id}"
puts"Name: #{bucket.name}"
puts"Storage Class: #{bucket.storage_class}"
puts"Location: #{bucket.location}"
puts"Location Type: #{bucket.location_type}"
puts"Cors: #{bucket.cors}"
puts"Default Event Based Hold: #{bucket.default_event_based_hold? }"
puts"Default KMS Key Name: #{bucket.default_kms_key }"
puts"Logging Bucket: #{bucket.logging_bucket }"
puts"Logging Prefix: #{bucket.logging_prefix }"
puts"Metageneration: #{bucket.metageneration}"
puts"Retention Effective Time: #{bucket.retention_effective_at }"
puts"Retention Period: #{bucket.retention_period }"
puts"Retention Policy Locked: #{bucket.retention_policy_locked? }"
puts"Requester Pays: #{bucket.requester_pays }"
puts"Self Link: #{bucket.api_url}"
puts"Time Created: #{bucket.created_at}"
puts"Versioning Enabled: #{bucket.versioning? }"
puts"Index Page: #{bucket.website_main }"
puts"Not Found Page: #{bucket.website_404 }"
puts"Labels:"
bucket.labels.each do|key,value|
puts" - #{key} = #{value}"
end
puts"Lifecycle Rules:"
bucket.lifecycle.each do|rule|
puts"#{rule.action } - #{rule.storage_class} - #{rule.age } - #{rule.matches_storage_class }"
end
end
Terraform
You can use a Terraform resource to view a bucket's metadata.
# Get bucket metadata
data "google_storage_bucket" "default" {
name = google_storage_bucket.static.id
}
output "bucket_metadata" {
value = data.google_storage_bucket.default
}REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorizationheader.Use
cURLto call the JSON API with aGETBucket request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"
Where
BUCKET_NAMEis the name of the relevant bucket. For example,my-bucket.Optionally, you can narrow down the metadata results by using the
fieldsquery string parameter. For example:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=FIELD1%2CFIELD2"
Where
FIELD#is a bucket property you want to include in the result. For example,projectNumberandstorageClass.
The response looks like the following example:
{ "projectNumber":"123456789012", "storageClass":"STANDARD" }
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorizationheader.Use
cURLto call the XML API with aGETBucket request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?QUERY_PARAMETER"
Where:
BUCKET_NAMEis the name of the relevant bucket. For example,my-bucket.QUERY_PARAMETERis the metadata field you want to return. For example,storageClassfor getting the bucket's storage class. You can only use one query parameter at a time with the XML API. For a list of metadata fields supported by the XML API, see theGETBucket reference page.
The response looks like the following example:
<StorageClass>STANDARD</StorageClass>.
What's next
- Read the bucket metadata overview.
- List the objects in your bucket.
- Get the size of your bucket.
- Get object metadata.
- Change the default storage class for your bucket.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get 300ドル in free credits to run, test, and deploy workloads.
Try Cloud Storage free