Using Object Versioning

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

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{true}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::runtime_error(patched.status().message());

  if (patched->versioning().has_value()) {
    std::cout << "Object versioning for bucket " << bucket_name << " is "
              << (patched->versioning()->enabled ? "enabled" : "disabled")
              << "\n";
  } else {
    std::cout << "Object versioning for bucket " << bucket_name
              << " is disabled.\n";
  }
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// enableVersioning enables object versioning on a bucket.
func enableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: true,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was enabled for %v\n", bucketName)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class EnableBucketVersioning {
  public static void enableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(true).build().update();

    System.out.println("Versioning is now enabled for bucket " + bucketName);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: true,
    },
  });

  console.log(`Versioning is enabled for bucket ${bucketName}.`);
}

enableBucketVersioning();

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def enable_versioning(bucket_name):
    """Enable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.versioning_enabled = True
    bucket.patch()

    print("Versioning was enabled for bucket {}".format(bucket.name))
    return bucket

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

def enable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  bucket.versioning = true

  puts "Versioning was enabled for bucket #{bucket_name}"
end

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

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

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{false}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::runtime_error(patched.status().message());

  if (patched->versioning().has_value()) {
    std::cout << "Object versioning for bucket " << bucket_name << " is "
              << (patched->versioning()->enabled ? "enabled" : "disabled")
              << "\n";
  } else {
    std::cout << "Object versioning for bucket " << bucket_name
              << " is disabled.\n";
  }
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// disableVersioning disables object versioning on a bucket.
func disableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: false,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was disabled for %v\n", bucketName)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DisableBucketVersioning {
  public static void disableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(false).build().update();

    System.out.println("Versioning is now disabled for bucket " + bucketName);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function disableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: false,
    },
  });

  console.log(`Versioning is disabled for bucket ${bucketName}.`);
}

disableBucketVersioning();

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def disable_versioning(bucket_name):
    """Disable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.versioning_enabled = False
    bucket.patch()

    print("Versioning was disabled for bucket {}".format(bucket))
    return bucket

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

def disable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  bucket.versioning = false

  puts "Versioning was disabled for bucket #{bucket_name}"
end

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

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 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://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 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

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 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_NAME2#GENERATION_NUMBER2
gs://BUCKET_NAME/OBJECT_NAME3#GENERATION_NUMBER3
...

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name) {
  for (auto&& object_metadata :
       client.ListObjects(bucket_name, gcs::Versions{true})) {
    if (!object_metadata) {
      throw std::runtime_error(object_metadata.status().message());
    }

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name()
              << ", generation=" << object_metadata->generation() << "\n";
  }
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listFilesAllVersion lists both live and noncurrent versions of objects within specified bucket.
func listFilesAllVersion(w io.Writer, bucket string) error {
	// bucket := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	it := client.Bucket(bucket).Objects(ctx, &storage.Query{
		// Versions true to output all generations of objects
		Versions: true,
	})
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects(): %v", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name, attrs.Generation, attrs.Metageneration)
	}
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListObjectsWithOldVersions {
  public static void listObjectsWithOldVersions(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";
    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    Page<Blob> blobs = bucket.list(Storage.BlobListOption.versions(true));

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName() + "," + blob.getGeneration());
    }
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function listFilesWithOldVersions() {
  const [files] = await storage.bucket(bucketName).getFiles({
    versions: true,
  });

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name, file.generation);
  });
}

listFilesWithOldVersions().catch(console.error);

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def list_file_archived_generations(bucket_name):
    """Lists all the blobs in the bucket with generation."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    blobs = storage_client.list_blobs(bucket_name)

    for blob in blobs:
        print("{},{}".format(blob.name, blob.generation))

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

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

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

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& source_bucket_name,
   std::string const& source_object_name,
   std::string const& destination_bucket_name,
   std::string const& destination_object_name,
   std::int64_t source_object_generation) {
  StatusOr<gcs::ObjectMetadata> copy =
      client.CopyObject(source_bucket_name, source_object_name,
                        destination_bucket_name, destination_object_name,
                        gcs::SourceGeneration{source_object_generation});
  if (!copy) throw std::runtime_error(copy.status().message());

  std::cout << "Successfully copied " << source_object_name << " generation "
            << source_object_generation << " in bucket " << source_bucket_name
            << " to bucket " << copy->bucket() << " with name "
            << copy->name()
            << ".\nThe full metadata after the copy is: " << *copy << "\n";
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// copyOldVersionOfObject copies a noncurrent version of an object.
func copyOldVersionOfObject(w io.Writer, bucket, srcObject, dstObject string, gen int64) error {
	// bucket := "bucket-name"
	// srcObject := "source-object-name"
	// dstObject := "destination-object-name"

	// gen is the generation of srcObject to copy.
	// gen := 1587012235914578
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	src := client.Bucket(bucket).Object(srcObject)
	dst := client.Bucket(bucket).Object(dstObject)

	if _, err := dst.CopierFrom(src.Generation(gen)).Run(ctx); err != nil {
		return fmt.Errorf("Object(%q).CopierFrom(%q).Generation(%v).Run: %v", dstObject, srcObject, gen, err)
	}
	fmt.Fprintf(w, "Generation %v of object %v in bucket %v was copied to %v\n", gen, srcObject, bucket, dstObject)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class CopyOldVersionOfObject {
  public static void copyOldVersionOfObject(
      String projectId,
      String bucketName,
      String objectToCopy,
      long generationToCopy,
      String newObjectName) {
    // 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 the GCS object to copy an old version of
    // String objectToCopy = "your-object-name";

    // The generation of objectToCopy to copy
    // long generationToCopy = 1579287380533984;

    // What to name the new object with the old data from objectToCopy
    // String newObjectName = "your-new-object";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Storage.CopyRequest copyRequest =
        Storage.CopyRequest.newBuilder()
            .setSource(BlobId.of(bucketName, objectToCopy, generationToCopy))
            .setTarget(BlobId.of(bucketName, newObjectName))
            .build();
    storage.copy(copyRequest);

    System.out.println(
        "Generation "
            + generationToCopy
            + " of object "
            + objectToCopy
            + " in bucket "
            + bucketName
            + " was copied to "
            + newObjectName);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const srcBucketName = 'Name of the source bucket, e.g. my-bucket';
// const srcFilename = 'Name of the source file, e.g. file.txt';
// const destBucketName = 'Name of the destination bucket, e.g. my-other-bucket';
// const destFilename = 'Destination name of file, e.g. file.txt';
// const generation = 'The generation of file to copy, e.g. 1'

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function copyOldVersionOfFile() {
  // Copies the file to the other bucket
  await storage
    .bucket(srcBucketName)
    .file(srcFilename, {
      generation,
    })
    .copy(storage.bucket(destBucketName).file(destFilename));

  console.log(
    `Generation ${generation} of file ${srcFilename} in bucket ${srcBucketName} was copied to ${destFilename} in bucket ${destBucketName}.`
  );
}

copyOldVersionOfFile().catch(console.error);

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def copy_file_archived_generation(
        bucket_name, blob_name, destination_bucket_name, destination_blob_name, generation
):
    """Copies a blob from one bucket to another with a new name with the same generation."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # destination_bucket_name = "destination-bucket-name"
    # destination_blob_name = "destination-object-name"
    # generation = 1579287380533984

    storage_client = storage.Client()

    source_bucket = storage_client.bucket(bucket_name)
    source_blob = source_bucket.blob(blob_name)
    destination_bucket = storage_client.bucket(destination_bucket_name)

    blob_copy = source_bucket.copy_blob(
        source_blob, destination_bucket, destination_blob_name, source_generation=generation
    )

    print(
        "Generation {} of the blob {} in bucket {} copied to blob {} in bucket {}.".format(
            source_blob.generation,
            source_blob.name,
            source_bucket.name,
            blob_copy.name,
            destination_bucket.name,
        )
    )

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

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

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation.

View on GitHub Feedback

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::int64_t object_generation) {
  google::cloud::Status status = client.DeleteObject(
      bucket_name, object_name, gcs::Generation{object_generation});
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "Deleted " << object_name << " generation "
            << object_generation << " in bucket " << bucket_name << "\n";
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// deleteOldVersionOfObject deletes a noncurrent version of an object.
func deleteOldVersionOfObject(w io.Writer, bucketName, objectName string, gen int64) error {
	// bucketName := "bucket-name"
	// objectName := "object-name"

	// gen is the generation of objectName to delete.
	// gen := 1587012235914578
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	obj := client.Bucket(bucketName).Object(objectName)
	if err := obj.Generation(gen).Delete(ctx); err != nil {
		return fmt.Errorf("Bucket(%q).Object(%q).Generation(%v).Delete: %v", bucketName, objectName, gen, err)
	}
	fmt.Fprintf(w, "Generation %v of object %v was deleted from %v\n", gen, objectName, bucketName)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DeleteOldVersionOfObject {
  public static void deleteOldVersionOfObject(
      String projectId, String bucketName, String objectName, long generationToDelete) {
    // 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";

    // The generation of objectName to delete
    // long generationToDelete = 1579287380533984;

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    storage.delete(BlobId.of(bucketName, objectName, generationToDelete));

    System.out.println(
        "Generation "
            + generationToDelete
            + " of object "
            + objectName
            + " was deleted from "
            + bucketName);
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to delete, e.g. file.txt';
// const generation = 'Generation of file to delete, e.g. 1';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function deleteOldVersionOfFile() {
  // Deletes the file from the bucket with given version
  await storage
    .bucket(bucketName)
    .file(filename, {
      generation,
    })
    .delete();

  console.log(
    `Generation ${generation} of file ${filename} was deleted from ${bucketName}.`
  );
}

deleteOldVersionOfFile().catch(console.error);

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def delete_file_archived_generation(bucket_name, blob_name, generation):
    """Delete a blob in the bucket with the given generation."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # generation = 1579287380533984

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.delete_blob(blob_name, generation=generation)
    print(
        "Generation {} of blob {} was deleted from {}".format(
            generation, blob_name, bucket_name
        )
    )

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

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

What's next

Learn more about Object Versioning.
Learn how to use Object Lifecycle Management to automatically manage object versions.