Change object storage classes
This page describes how to change the storage class of objects within a bucket through rewriting the object.
- To learn how to change object storage classes without rewriting an object, see the Object Lifecycle Management feature.
- To learn how Cloud Storage can automatically manage your object's storage classes, see the Autoclass feature.
Required roles
In order to get the required permissions for changing the storage class of
an object through rewriting the object, ask your administrator to grant you the
Storage Object User (roles/storage.objectUser) role on the bucket.
This role contains the permissions required to change the storage class of an object. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
storage.objects.createstorage.objects.deletestorage.objects.getstorage.objects.list
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.
Change an object's storage class
Complete the following steps to change an object's storage class:
Console
Individual object storage classes cannot be set through the Google Cloud console. Instead, use the Google Cloud CLI.
Command line
Use the gcloud storage objects update command with the
--storage-class flag. For example:
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --storage-class=STORAGE_CLASS
Where:
BUCKET_NAMEis the name of the bucket containing the object whose class you want to change. For example,my-bucket.OBJECT_NAMEis the name of the object whose class you want to change. For example,pets/dog.png.STORAGE_CLASSis the new storage class for your object. For example,nearline.
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,
std::stringconst&object_name,std::stringconst&storage_class){
StatusOr<gcs::ObjectMetadata>object_metadata=
client.RewriteObjectBlocking(
bucket_name,object_name,bucket_name,object_name,
gcs::WithObjectMetadata(
gcs::ObjectMetadata().set_storage_class(storage_class)));
if(!object_metadata)throwstd::move(object_metadata).status();
std::cout << "Changed storage class of object " << object_metadata->name()
<< " in bucket " << object_metadata->bucket() << " to "
<< object_metadata->storage_class() << "\n";
}C#
usingGoogle.Cloud.Storage.V1 ;
usingSystem;
publicclassChangeFileStorageClassSample
{
publicGoogle.Apis.Storage.v1.Data.ObjectChangeFileStorageClass(
stringbucketName="your-bucket-name",
stringobjectName="your-object-name",
stringstorageClass=StorageClasses .Standard )
{
varstorage=StorageClient .Create ();
// Changing storage class requires a rewrite operation, which can only be done
// by the underlying service
varobj=newGoogle.Apis.Storage.v1.Data.Object{StorageClass=storageClass};
storage.Service.Objects.Rewrite(obj,bucketName,objectName,bucketName,objectName).Execute();
varfile=storage.GetObject(bucketName,objectName);
Console.WriteLine($"Object {objectName} in bucket {bucketName} had"+
$" its storage class set to {storageClass}.");
returnfile;
}
}Go
import(
"context"
"fmt"
"io"
"time"
"cloud.google.com/go/storage"
)
// changeObjectStorageClass changes the storage class of a single object.
funcchangeObjectStorageClass(wio.Writer ,bucket,objectstring)error{
// bucket := "bucket-name"
// object := "object-name"
ctx:=context.Background()
client,err:=storage.NewClient(ctx)
iferr!=nil{
returnfmt.Errorf("storage.NewClient: %w",err)
}
deferclient.Close()
ctx,cancel:=context.WithTimeout(ctx,time.Second*10)
defercancel()
o:=client.Bucket (bucket).Object (object)
// Optional: set a generation-match precondition to avoid potential race
// conditions and data corruptions. The request to copy is aborted if the
// object's generation number does not match your precondition.
attrs,err:=o.Attrs(ctx)
iferr!=nil{
returnfmt.Errorf("object.Attrs: %w",err)
}
o=o.If(storage.Conditions {GenerationMatch:attrs.Generation })
// See the StorageClass documentation for other valid storage classes:
// https://cloud.google.com/storage/docs/storage-classes
newStorageClass:="COLDLINE"
// You can't change an object's storage class directly, the only way is
// to rewrite the object with the desired storage class.
copier:=o.CopierFrom (o)
copier.StorageClass=newStorageClass
if_,err:=copier.Run(ctx);err!=nil{
returnfmt.Errorf("copier.Run: %w",err)
}
fmt.Fprintf(w,"Object %v in bucket %v had its storage class set to %v\n",object,bucket,newStorageClass)
returnnil
}
Java
importcom.google.cloud.storage.Blob ;
importcom.google.cloud.storage.BlobId ;
importcom.google.cloud.storage.BlobInfo ;
importcom.google.cloud.storage.Storage ;
importcom.google.cloud.storage.StorageClass ;
importcom.google.cloud.storage.StorageOptions ;
publicclass ChangeObjectStorageClass{
publicstaticvoidchangeObjectStorageClass(
StringprojectId,StringbucketName,StringobjectName){
// The ID of your GCP project
// String projectId = "your-project-id";
// The ID of your GCS bucket
// String bucketName = "your-unique-bucket-name";
// The ID of your GCS object
// String objectName = "your-object-name";
Storage storage=StorageOptions .newBuilder().setProjectId(projectId).build().getService ();
BlobId blobId=BlobId .of(bucketName,objectName);
Blob sourceBlob=storage.get (blobId);
if(sourceBlob==null){
System.out.println("The object "+objectName+" wasn't found in "+bucketName);
return;
}
// See the StorageClass documentation for other valid storage classes:
// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
StorageClass storageClass=StorageClass .COLDLINE;
// You can't change an object's storage class directly, the only way is to rewrite the object
// with the desired storage class
BlobInfo targetBlob=BlobInfo .newBuilder(blobId).setStorageClass(storageClass).build();
// Optional: set a generation-match precondition to avoid potential race
// conditions and data corruptions. The request to upload returns a 412 error if
// the object's generation number does not match your precondition.
Storage .BlobSourceOptionprecondition=
Storage .BlobSourceOption.generationMatch(sourceBlob.getGeneration());
Storage .CopyRequest request=
Storage .CopyRequest.newBuilder()
.setSource(blobId)
.setSourceOptions(precondition)// delete this line to run without preconditions
.setTarget(targetBlob)
.build();
Blob updatedBlob=storage.copy (request).getResult();
System.out.println(
"Object "
+objectName
+" in bucket "
+bucketName
+" had its storage class set to "
+updatedBlob.getStorageClass().name ());
}
}Node.js
// Imports the Google Cloud client library
const{Storage}=require('@google-cloud/storage');
// Creates a client
conststorage=newStorage();
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';
// The ID of your GCS file
// const fileName = 'your-file-name';
// The name of a storage class
// See the StorageClass documentation for other valid storage classes:
// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
// const storageClass = 'coldline';
asyncfunctionfileChangeStorageClass(){
// Optional:
// Set a generation-match precondition to avoid potential race conditions
// and data corruptions. The request to copy is aborted if the object's
// generation number does not match your precondition. For a destination
// object that does not yet exist, set the ifGenerationMatch precondition to 0
// If the destination object already exists in your bucket, set instead a
// generation-match precondition using its generation number.
constsetStorageClassOptions={
ifGenerationMatch:generationMatchPrecondition,
};
awaitstorage
.bucket(bucketName)
.file(fileName)
.setStorageClass(storageClass,setStorageClassOptions);
console.log(`${fileName} has been set to ${storageClass}`);
}
fileChangeStorageClass().catch(console.error);PHP
use Google\Cloud\Storage\StorageClient;
/**
* Change the storage class of the given file.
*
* @param string $bucketName The name of your Cloud Storage bucket.
* (e.g. 'my-bucket')
* @param string $objectName The name of your Cloud Storage object.
* (e.g. 'my-object')
* @param string $storageClass The storage class of the new object.
* (e.g. 'COLDLINE')
*/
function change_file_storage_class(string $bucketName, string $objectName, string $storageClass): void
{
$storage = new StorageClient();
$bucket = $storage->bucket($bucketName);
$object = $bucket->object($objectName);
// Storage class cannot be changed directly. But we can rewrite the object
// using the new storage class.
$newObject = $object->rewrite($bucket, [
'storageClass' => $storageClass,
]);
printf(
'Object %s in bucket %s had its storage class set to %s',
$objectName,
$bucketName,
$newObject->info()['storageClass']
);
}Python
fromgoogle.cloudimport storage
defchange_file_storage_class(bucket_name, blob_name):
"""Change the default storage class of the blob"""
# bucket_name = "your-bucket-name"
# blob_name = "your-object-name"
storage_client = storage .Client ()
bucket = storage_client.bucket (bucket_name)
blob = bucket.blob(blob_name)
generation_match_precondition = None
# Optional: set a generation-match precondition to avoid potential race
# conditions and data corruptions. The request is aborted if the
# object's generation number does not match your precondition.
blob.reload() # Fetch blob metadata to use in generation_match_precondition.
generation_match_precondition = blob.generation
blob.update_storage_class ("NEARLINE", if_generation_match=generation_match_precondition)
print(
"Blob {} in bucket {} had its storage class set to {}".format(
blob_name,
bucket_name,
blob.storage_class
)
)
return blobRuby
defchange_file_storage_classbucket_name:,file_name:
# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# The ID of your GCS object
# file_name = "your-file-name"
require"google/cloud/storage"
storage=Google::Cloud::Storage .new
bucket=storage.bucketbucket_name,skip_lookup:true
file=bucket.file file_name
file.storage_class="NEARLINE"
puts"File #{file_name} in bucket #{bucket_name} had its storage class set to #{file.storage_class}"
end
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorizationheader.Create a JSON file that contains the following information:
{ "storageClass":"STORAGE_CLASS" }
Where:
STORAGE_CLASSis the new storage class for your object. For example,nearline.
Use
cURLto call the JSON API with aPOSTObject, request:curl -X POST --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
JSON_FILE_NAMEis the path for the JSON file that you created in Step 2.BUCKET_NAMEis the name of the bucket containing the original object. For example,my-bucket.OBJECT_NAMEis the URL-encoded name of the object. For example,pets/dog.png, URL-encoded aspets%2Fdog.png.
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 aPUTObject request:curl -X PUT --data-binary @OBJECT \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-storage-class: STORAGE_CLASS" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OBJECTis the local path to the object whose storage class you want to change (you must re-upload the object when changing storage class with the XML API). For example,Desktop/dog.png.OBJECT_CONTENT_TYPEis the content type of the object. For example,image/png.STORAGE_CLASSis the new storage class for your object. For example,nearline.BUCKET_NAMEis the name of the bucket containing the object you are rewriting. For example,my-bucket.OBJECT_NAMEis the URL-encoded name of the object you are rewriting. For example,pets/dog.png, URL-encoded aspets%2Fdog.png.
What's next
- Learn about available storage classes.
- Change object storage classes with Object Lifecycle Management.
- Explore other Cloud Storage data lifecycle features.
- Learn about object metadata.
- Learn how to use request preconditions to prevent race conditions.