This page describes how to set up Object Versioning and gives examples of using Object Versioning.
Setting up Object Versioning
The following sections show how to turn Object Versioning on and off using the gsutil tool, the JSON API, and the XML API. Object Versioning cannot currently be controlled using the Google Cloud Console.
Enabling Object Versioning
To enable Object Versioning on a bucket:
gsutil
Use the gsutil versioning set on
command:
gsutil versioning set on gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
Go
Java
Node.js
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a
.json
file that contains the following information:{ "versioning": { "enabled": true } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"
Where:
JSON_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create an
.xml
file that contains the following information:<VersioningConfiguration> <Status>Enabled</Status> </VersioningConfiguration>
Use
cURL
to call the XML API, with aPUT
Bucket request andversioning
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?versioning"
Where:
XML_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Once Object Versioning is enabled, each time a live object version is replaced or deleted, that version becomes a noncurrent version.
Disabling Object Versioning
To disable Object Versioning on a bucket:
gsutil
Use the gsutil versioning set off
command:
gsutil versioning set off gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
Go
Java
Node.js
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a
.json
file that contains the following information:{ "versioning": { "enabled": false } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"
Where:
JSON_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create an
.xml
file that contains the following information:<VersioningConfiguration> <Status>Suspended</Status> </VersioningConfiguration>
Use
cURL
to call the XML API, with aPUT
Bucket request andversioning
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?versioning"
Where:
XML_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Checking whether Object Versioning is enabled
To check whether Object Versioning is enabled on a bucket:
gsutil
Use the gsutil versioning get
command:
gsutil versioning get gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
The response looks like the following if Object Versioning is enabled:
gs://my-bucket: Enabled
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"
Where:
OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API, with aGET
Bucket request andversioning
query string parameter:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?versioning"
Where:
OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Working with versioned objects
The following sections show how to work with versioned objects. For an in-depth example of working with Object Versioning, see Object Versioning example.
Listing noncurrent object versions
To list both live and noncurrent versions of an object and view their
generation
numbers:
gsutil
Use the gsutil ls -a
command:
gsutil ls -a gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. 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 ...
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
C++
Go
Java
Node.js
Python
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aLIST
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?versions=true"
Where:
OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Noncurrent versions of objects have a timeDeleted
property.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API, with aGET
Bucket request andversions
query string parameter:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?versions"
Where:
OAUTH2_TOKEN
is the access token you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. 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.
Accessing 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:
gsutil
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 step 1, proceed as you normally would for the live version of the object.
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 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 URI from step 1, proceed as you normally would for the live version of the object.
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 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 URI from step 1, proceed as you normally would for the live version of the object.
Copying noncurrent object versions
To copy a noncurrent version of an object:
gsutil
Use the gsutil cp
command:
gsutil cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME#GENERATION_NUMBER gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME
Where:
SOURCE_BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to copy. For example,my-bucket
.SOURCE_OBJECT_NAME
is the name of the noncurrent version you want to copy. For example,pets/dog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to copy. For example,1560468815691234
.DESTINATION_BUCKET_NAME
is the name of the bucket where you want to copy the noncurrent version. For example,my-bucket
.DESTINATION_OBJECT_NAME
is the name of the noncurrent version copy. For example,pets/shiba.png
.
If successful, the response looks like the following example:
Operation completed over 1 objects/58.8 KiB.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
C++
Go
Java
Node.js
Python
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Length: 0" \ "https://storage.googleapis.com/upload/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/NAME_OF_COPY?sourceGeneration=GENERATION_NUMBER"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SOURCE_BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to copy. For example,my-bucket
.SOURCE_OBJECT_NAME
is the name of the noncurrent version you want to copy. For example,pets/dog.png
.DESTINATION_BUCKET_NAME
is the name of the bucket where you want to copy the noncurrent version. For example,my-bucket
.NAME OF COPY
is the name of the noncurrent version copy. For example,pets/shiba.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to copy. For example,1560468815691234
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API, with aPUT
Object request:curl -X PUT \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "x-goog-copy-source: SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME" \ -H "x-goog-copy-source-generation:GENERATION_NUMBER" \ "https://storage.googleapis.com/DESTINATION_BUCKET_NAME/NAME_OF_COPY"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SOURCE_BUCKET_NAME
is the name of the bucket containing the noncurrent version you want to copy. For example,my-bucket
.SOURCE_OBJECT_NAME
is the name of the noncurrent version you want to copy. For example,pets/dog.png
.GENERATION_NUMBER
is the generation number for the noncurrent version you want to copy. For example,1560468815691234
.DESTINATION_BUCKET_NAME
is the name of the bucket where you want to copy the noncurrent version. For example,my-bucket
.NAME OF COPY
is the name of the noncurrent version copy. For example,pets/shiba.png
.
Deleting noncurrent object versions
To delete a noncurrent version of an object:
gsutil
Use the gsutil rm
command:
gsutil 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.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
C++
Go
Java
Node.js
Python
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aDELETE
Object request:curl -X DELETE \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API, with aDELETE
Object request:curl -X DELETE \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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
.
What's next
- Learn more about Object Versioning.
- Learn how to use Object Lifecycle Management to automatically manage object versions.