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 Platform Console.

Enabling Object Versioning

To enable Object Versioning on a bucket:

gsutil

Use the gsutil versioning set on command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil versioning set on gs://[BUCKET_NAME]

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:
  3. {
      "versioning": {
        "enabled": true
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <VersioningConfiguration>
      <Status>Enabled</Status>
    </VersioningConfiguration>
  3. Use cURL to call the XML API, with a PUT Bucket request and versioning query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

Disabling Object Versioning

To disable Object Versioning on a bucket:

gsutil

Use the gsutil versioning set off command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil versioning set off gs://[BUCKET_NAME]

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:
  3. {
      "versioning": {
        "enabled": false
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <VersioningConfiguration>
      <Status>Suspended</Status>
    </VersioningConfiguration>
  3. Use cURL to call the XML API, with a PUT Bucket request and versioning query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

Checking whether Object Versioning is enabled

To check whether Object Versioning is enabled on a bucket:

gsutil

Use the gsutil versioning get command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil versioning get gs://[BUCKET_NAME]

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

Working with versioned objects

The following sections show how to work with versioned objects.

Listing archived object versions

To list both live and archived versions of an object and view their generation numbers:

gsutil

Use the gsutil ls -a command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil ls -a gs://[BUCKET_NAME]

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

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o?versions=true"

Archived 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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?versions"

There are a few differences in the results of the GET request when using the versions query parameter compared to not using it. Specifically, Google 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 was archived (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 archived object versions

To access an archived version of an object:

gsutil

  1. Append the generation number of the archived object to the object name by replacing the [VALUES_IN_BRACKETS] with appropriate values:

    [OBJECT_NAME]#[GENERATION_NUMBER]

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

REST APIs

JSON API

  1. Append the generation number of the archived object to the URI for the object by replacing the [VALUES_IN_BRACKETS] with appropriate values:
    https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?generation=[GENERATION_NUMBER]
  2. Using the URI from step 1, proceed as you normally would for a live object.

XML API

  1. Append the generation number of the archived object to the URI for the object by replacing the [VALUES_IN_BRACKETS] with appropriate values:
    https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]?generation=[GENERATION_NUMBER]
  2. Using the URI from step 1, proceed as you normally would for a live object.

Copying archived object versions

To copy an archived version of an object:

gsutil

Use the gsutil cp command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil cp gs://[SOURCE_BUCKET_NAME]/[SOURCE_OBJECT_NAME]#[GENERATION_NUMBER] gs://[DESTINATION_BUCKET_NAME]/[DESTINATION_OBJECT_NAME]

If successful, the response looks like the following example:

Operation completed over 1 objects/58.8 KiB.

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X POST \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Length: 0" \
        "https://www.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]"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    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]"

Deleting archived object versions

To delete an archived version of an object:

gsutil

Use the gsutil rm command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil rm gs://[BUCKET_NAME]/[OBJECT_NAME]#[GENERATION_NUMBER]

If successful, the response looks like the following example:

Operation completed over 1 objects.

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X DELETE \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?generation=[GENERATION_NUMBER]"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X DELETE \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]?generation=[GENERATION_NUMBER]"

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Storage