Using Object Versioning

This page describes how to set up Object Versioning and gives examples of using Object Versioning. For a description of this feature, see 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

Note: Object Versioning cannot be enabled on a bucket that currently has a retention policy.

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.

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. Create a .json file that contains the following information:

   {
     "versioning": {
       "enabled": true
     }
   }

3. Use cURL to call the JSON API with a PATCH 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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create an .xml file that contains the following information:

   <VersioningConfiguration>
     <Status>Enabled</Status>
   </VersioningConfiguration>

3. Use cURL to call the XML API, with a PUT Bucket request and versioning 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, Cloud Storage creates a noncurrent version of an object each time the live version of the object is overwritten or deleted.

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.

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. Create a .json file that contains the following information:

   {
     "versioning": {
       "enabled": false
     }
   }

3. Use cURL to call the JSON API with a PATCH 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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create an .xml file that contains the following information:

   <VersioningConfiguration>
     <Status>Suspended</Status>
   </VersioningConfiguration>

3. Use cURL to call the XML API, with a PUT Bucket request and versioning 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://[BUCKET_NAME]: Enabled

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:

   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

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 and versioning 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_NAME1]#[GENERATION_NUMBER2]
gs://[BUCKET_NAME]/[OBJECT_NAME1]#[GENERATION_NUMBER3]
...

Note: Use the -l flag along with the -a flag to get metageneration numbers in the response. Use the -L flag along with the -a flag to get the Archived Time for noncurrent versions of an object.

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

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 and versions 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 overwritten).
• 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 the generationmarker query parameter of subsequent requests in order to resume from your last point. The generationmarker query parameter is used in the same way that you use the marker 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

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

2. Using the string from step 1, proceed as you normally would for the live version of the object.

REST APIs

JSON API

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

2. Using the URI from step 1, proceed as you normally would for the live version of the object.

XML API

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

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

Note: Some shells, such as zsh when the extendedglob option is enabled, treat the hash character, #, as a special character. If this is the case for your shell, you should enclose that argument in single quotes (or double quotes for Windows).

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

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

Note: You can remove all versions of an object, including live and noncurrent versions, by using the -a flag and omitting the #[GENERATION_NUMBER].

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

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