This page describes how to list, access, restore, and delete noncurrent objects, which typically applies to buckets with the feature Object Versioning enabled.
Required roles
To get the permissions that you need to manage noncurrent objects, ask your
administrator to grant you the Storage Object User (roles/storage.objectUser
)
IAM role on the project. This predefined role contains the
permissions required to manage noncurrent objects. To see the exact
permissions that are required, expand the Required permissions section:
Required permissions
storage.objects.create
storage.objects.delete
storage.objects.get
storage.objects.list
You might also be able to get these permissions with custom roles.
For information about granting roles on projects, see Manage access to projects.
Depending on your use case, you might need additional permissions or alternative roles:
If you plan on using the Google Cloud console to perform the tasks on this page, you'll also need the
storage.buckets.list
permission, which is not included in the Storage Object User (roles/storage.objectUser
) role. To get this permission, ask your administrator to grant you the Storage Admin (roles/storage.admin
) role on the project.If uniform bucket-level access is disabled for your bucket, you need additional permissions in the following scenarios:
If you plan on returning noncurrent objects along with their ACLs, you also need the
storage.objects.getIamPolicy
permission, which is not included in the Storage Object User (roles/storage.objectUser
) role. To get this permission, ask your administrator to grant you the Storage Object Admin (roles/storage.objectAdmin
) role on the project.If you plan on renaming or restoring noncurrent objects that have ACLs, you also need the
storage.objects.setIamPolicy
permission, which is not included in the Storage Object User (roles/storage.objectUser
) role. To get this permission, ask your administrator to grant you the Storage Object Admin (roles/storage.objectAdmin
) role on the project.
List noncurrent object versions
To list both live and noncurrent versions of objects and view their
generation
numbers:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket that contains the wanted object.
The Bucket details page opens, with the Objects tab selected.
To view noncurrent objects, click the Show drop-down and select Live and noncurrent objects.
In the list of objects, click the name of the object whose versions you want to see.
The Object details page opens, with the Live Object tab selected.
Click the Version history tab to see all versions of the object.
Command line
Use the gcloud storage ls --all-versions
command:
gcloud storage ls --all-versions gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket that
contains the objects. For example, my-bucket
.
The response looks like the following example:
gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1 gs://BUCKET_NAME/OBJECT_NAME2#GENERATION_NUMBER2 gs://BUCKET_NAME/OBJECT_NAME3#GENERATION_NUMBER3 ...
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with an Objects: list request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?versions=true"
Where
BUCKET_NAME
is the name of the bucket that contains the objects. For example,my-bucket
.
Noncurrent versions of objects have a timeDeleted
property.
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the XML API, with aGET
Bucket request andversions
query string parameter:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?versions&list-type=2"
Where
BUCKET_NAME
is the name of the bucket that contains the objects. For example,my-bucket
.
There are a few differences in the results of the GET
request when
using the versions
query parameter compared to not using it.
Specifically, Cloud Storage returns the following information when
you include a versions
query parameter in your request:
- A
Version
element that contains information about each object. - A
DeletedTime
element that contains the time the object version became noncurrent (deleted or replaced). - An `IsLatest element that indicates if the specific object is the latest version.
- A
NextGenerationMarker
element is returned if the listing of objects is a partial listing, which occurs when you have many object versions in a bucket. Use the value of this element in thegenerationmarker
query parameter of subsequent requests in order to resume from your last point. Thegenerationmarker
query parameter is used in the same way that you use themarker
query parameter to page through a listing for a nonversioned bucket.
Access noncurrent object versions
To use the noncurrent version of an object when performing tasks such as downloading the object, viewing its metadata, or updating its metadata:
Console
General access to a noncurrent version is not available in the Google Cloud console. Using the Google Cloud console, you can only move, copy, restore or delete a noncurrent version. These actions are performed from the version history list for an object.
Command line
Append the generation number of the noncurrent version to the object name:
OBJECT_NAME#GENERATION_NUMBER
Where:
OBJECT_NAME
is the name of the noncurrent version. For example,pets/dog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version. For example,1560468815691234
.
Using the string from the previous step, proceed as you normally would for the live version of the object. For example, to view the metadata of a noncurrent object version, use the
gcloud storage objects describe
command:gcloud storage objects describe gs://my-bucket/pets/dog.png#1560468815691234
REST APIs
JSON API
Append the generation number of the noncurrent version to the URI for the object:
https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version. For example,1560468815691234
.
Using the URI from the previous step, proceed as you normally would for the live version of the object. For example, to view the metadata of a noncurrent object version, use cURL to call the JSON API with an Objects: get request:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/my-bucket/o/pets/dog.png?generation=1560468815691234"
XML API
Append the generation number of the noncurrent version to the URI for the object:
https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version. For example,1560468815691234
.
Using the URI from the previous step, proceed as you normally would for the live version of the object. For example, to view the metadata of a noncurrent object version, use
cURL
to call the XML API with aHEAD
Object request:curl -I GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/my-bucket/pets/dog.png?generation=1560468815691234"
Restore noncurrent object versions
In Cloud Storage, restoring a noncurrent object version means making a copy of it. When you do so, the copy becomes the live version, effectively restoring the version. If there is already a live version and the bucket has Object Versioning enabled, restoring the noncurrent version causes the pre-existing live version to become noncurrent.
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket that contains the wanted object.
The Bucket details page opens, with the Objects tab selected.
To view noncurrent objects, click the Show drop-down and select Live and noncurrent objects.
In the list of objects, click the name of the object version you want to restore.
The Object details page opens, with the Live Object tab selected.
Click the Version history tab.
Click the Restore button for the wanted version.
The restore object version pane opens.
Click Confirm.
Command line
Use the gcloud storage cp
command:
gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER gs://BUCKET_NAME/OBJECT_NAME
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to restore. For example,my-bucket
.OBJECT_NAME
is the name of the noncurrent version you want to restore. For example,pets/dog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to restore. For example,1560468815691234
.
If successful, the response looks like the following example:
Operation completed over 1 objects/58.8 KiB.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Length: 0" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME?sourceGeneration=GENERATION_NUMBER"
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to restore. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version you want to restore. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to restore. For example,1560468815691234
.
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the XML API, with aPUT
Object request:curl -X PUT \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-copy-source: BUCKET_NAME/OBJECT_NAME" \ -H "x-goog-copy-source-generation:GENERATION_NUMBER" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to restore. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version you want to restore. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to restore. For example,1560468815691234
.
After restoring the object version, the original noncurrent version continues to exist in the bucket. If you no longer need the noncurrent version, you can subsequently delete it or configure Object Lifecycyle Management to remove it when it meets the conditions you specify.
Delete noncurrent object versions
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket that contains the wanted object.
The Bucket details page opens, with the Objects tab selected.
To view noncurrent objects, click the Show drop-down and select Live and noncurrent objects.
Navigate to the object, which may be located in a folder.
In the list of objects, click the name of the object whose version you want to delete.
The Object details page opens, with the Live Object tab selected.
Click the Version history tab.
Select the checkbox for the wanted version.
Click the Delete button.
The delete version pane opens.
Confirm you want to delete the object by typing
delete
into the text field.Click Delete.
Command line
Use the gcloud storage rm
command:
gcloud storage rm gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to delete. For example,my-bucket
.OBJECT_NAME
is the name of the noncurrent version you want to delete. For example,pets/dog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to delete. For example,1560468815691234
.
If successful, the response looks like the following example:
Operation completed over 1 objects.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aDELETE
Object request:curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER"
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to delete. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version you want to delete. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to delete. For example,1560468815691234
.
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the XML API, with aDELETE
Object request:curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER"
Where:
BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to delete. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the noncurrent version you want to delete. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to delete. For example,1560468815691234
.
What's next
- Learn more about Object Versioning, including an in-depth example.
- Enable or disable Object Versioning on a bucket.
- Learn how to use Object Lifecycle Management to automatically manage object versions.