使用具有版本控制的对象

概览 设置

本页面介绍了如何列出、访问、恢复和删除非当前对象，这通常适用于启用了对象版本控制功能的存储桶。

所需权限

控制台

如需使用 Google Cloud 控制台完成本指南，您必须拥有适当的 IAM 权限。如果您要访问的存储桶在不是由您创建的项目中，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需权限的列表，请参阅 Google Cloud 控制台的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

命令行

为使用命令行实用程序完成本指南，您必须拥有适当的 IAM 权限。如果您要访问的存储桶在不是由您创建的项目中，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需权限的列表，请参阅 gsutil 命令的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

客户端库

如需使用 Cloud Storage 客户端库完成本指南，您必须拥有适当的 IAM 权限。如果您要访问的存储桶在不是由您创建的项目中，则可能需要项目所有者为您提供具有必要权限的角色。

除非另有说明，否则客户端库请求通过 JSON API 发出，并且需要 JSON 方法的 IAM 权限中列出的权限。如需查看使用客户端库发出请求时调用了哪些 JSON API 方法，请记录原始请求。

如需查看相关 IAM 角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

REST API

JSON API

如需使用 JSON API 完成本指南，您必须拥有适当的 IAM 权限。如果您要访问的存储桶在不是由您创建的项目中，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需的权限列表，请参阅 JSON 方法的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

列出非当前对象版本

如需列出对象的当前版本和非当前版本，并查看它们的 generation 编号，请执行以下操作：

控制台

注意：Google Cloud 控制台可以列出的对象版本的数量上限为 1000 个。如需查看对象的更多版本，请使用 gcloud CLI。

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击存放所需对象的存储桶的名称。

   此时会打开“存储桶详情”页面，其中对象标签页已选中。

3. 导航到可能位于文件夹中的对象。

4. 点击所需对象的名称。

   此时会打开“对象详情”页面，其中实时对象标签页已选中。

5. 点击版本记录标签页。

命令行

gcloud

使用 gcloud storage ls --all-versions 命令：

gcloud storage ls --all-versions gs://BUCKET_NAME

其中 BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

响应如下例所示：

gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1
gs://BUCKET_NAME/OBJECT_NAME2#GENERATION_NUMBER2
gs://BUCKET_NAME/OBJECT_NAME3#GENERATION_NUMBER3
...

注意：结合使用 --long 标志和 --all-versions 标志可在响应中获取元数据世代编号。结合使用 --full 标志和 --all-versions 标志可获取对象非当前版本的 Noncurrent Time。

gsutil

重要提示：gsutil 不是 Cloud Storage 推荐的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

使用 gsutil ls -a 命令：

gsutil ls -a gs://BUCKET_NAME

其中 BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

响应类似如下示例：

gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1
gs://BUCKET_NAME/OBJECT_NAME2#GENERATION_NUMBER2
gs://BUCKET_NAME/OBJECT_NAME3#GENERATION_NUMBER3
...

注意：结合使用 -l 标志和 -a 标志可在响应中获取元数据世代编号。结合使用 -L 标志和 -a 标志可获取对象非当前版本的 Noncurrent Time。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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::move(object_metadata).status();

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

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFileArchivedGenerationSample
{
	public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFileArchivedGeneration(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();

		var storageObjects = storage.ListObjects(bucketName, options: new ListObjectsOptions
		{
			Versions = true
		});

		foreach (var storageObject in storageObjects)
		{
			Console.WriteLine($"Filename: {storageObject.Name}, Generation: {storageObject.Generation}");
		}

		return storageObjects;
	}
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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: %w", 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(): %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name, attrs.Generation, attrs.Metageneration)
	}
	return nil
}

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// 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);

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * List objects in a specified bucket with all archived generations.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function list_file_archived_generations(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $objects = $bucket->objects([
        'versions' => true,
    ]);

    foreach ($objects as $object) {
        print($object->name() . ',' . $object->info()['generation'] . PHP_EOL);
    }
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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, versions=True)

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

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

def list_file_archived_generations 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.files.each do |file|
    puts "#{file.name},#{file.generation}"
  end
end

REST API

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 LIST Object 请求调用 JSON API：

   curl -X GET \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?versions=true"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中创建的访问令牌。
   • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

对象非当前版本具有 timeDeleted 属性。

XML API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 GET Bucket 请求和 versions 查询字符串参数调用 XML API：

   curl -X GET \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/BUCKET_NAME?versions&list-type=2"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中创建的访问令牌。
   • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

与不使用 versions 查询参数相比，在使用该查询参数时，GET 请求的结果存在一些差异。具体而言，当您在请求中包含 versions 查询参数时，Cloud Storage 会返回以下信息：

• Version 元素（包含每个对象的相关信息）。
• DeletedTime 元素（包含对象版本成为非当前版本（删除或替换）的时间）。
• IsLatest 元素（指示特定对象是否为最新版本）。
• 如果对象列出操作仅列出部分对象（当存储桶中包含许多对象版本时，会发生此情况），则会返回 NextGenerationMarker 元素。在后续请求的 generationmarker 查询参数中使用此元素的值，以便从上次的截止点继续。generationmarker 查询参数的使用方式与 marker 查询参数相同，用于为非版本化存储桶的列表结果分页。

访问非当前对象版本

如需在执行下载对象、查看其元数据或更新其元数据等任务时使用非当前对象版本，请执行以下操作：

控制台

Google Cloud 控制台不提供对非当前版本的常规访问权限。使用 Google Cloud 控制台时，您只能移动、复制、恢复或删除非当前版本。这些操作是从对象的版本记录列表中执行的。

命令行

gcloud

1. 将非当前版本的 generation 编号附加到对象名称：

   OBJECT_NAME#GENERATION_NUMBER

   其中：

   • OBJECT_NAME 是非当前版本的名称，例如 pets/dog.png。
   • GENERATION_NUMBER 是非当前版本的世代编号，例如 1560468815691234。

2. 使用第 1 步中的字符串，按照适用于对象当前版本的常规方式继续操作。

gsutil

重要提示：gsutil 不是 Cloud Storage 推荐的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

1. 将非当前版本的 generation 编号附加到对象名称：

   OBJECT_NAME#GENERATION_NUMBER

   其中：

   • OBJECT_NAME 是非当前版本的名称，例如 pets/dog.png。
   • GENERATION_NUMBER 是非当前版本的世代编号，例如 1560468815691234。

2. 使用第 1 步中的字符串，按照适用于对象当前版本的常规方式继续操作。

REST API

JSON API

1. 将非当前版本的 generation 编号附加到对象的 URI：

   https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER

   其中：

   • BUCKET_NAME 是包含非当前版本的存储桶的名称，例如 my-bucket。
   • OBJECT_NAME 是非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是非当前版本的世代编号，例如 1560468815691234。

2. 使用第 1 步中的 URI，按照适用于对象当前版本的常规方式继续操作。

XML API

1. 将非当前版本的 generation 编号附加到对象的 URI：

   https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER

   其中：

   • BUCKET_NAME 是包含非当前版本的存储桶的名称，例如 my-bucket。
   • OBJECT_NAME 是非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是非当前版本的世代编号，例如 1560468815691234。

2. 使用第 1 步中的 URI，按照适用于对象当前版本的常规方式继续操作。

注意：您不能发出覆盖或重写非当前对象的请求，因为 Cloud Storage 不支持指定目标对象的世代编号。

恢复非当前对象版本

在 Cloud Storage 中，恢复非当前对象版本意味着创建该版本的副本。执行此操作后，副本会成为当前版本，从而有效地恢复版本。如果已有当前版本并且存储桶启用了对象版本控制，则恢复非当前版本会导致之前存在的当前版本变为非当前版本。

控制台

注意：Google Cloud 控制台可以列出的对象版本的数量上限为 1000 个。

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击存放所需对象的存储桶的名称。

   此时会打开“存储桶详情”页面，其中对象标签页已选中。

   如需查看已删除的对象，请点击“显示已删除的数据”切换开关。

3. 导航到可能位于文件夹中的对象。

4. 点击所需对象的名称。

   此时会打开“对象详情”页面，其中实时对象标签页已选中。

5. 点击版本记录标签页。

6. 点击所需版本的恢复按钮。

   此时会打开恢复对象版本窗格。

7. 点击确认。

命令行

gcloud

使用 gcloud storage cp 命令：

gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER gs://BUCKET_NAME/OBJECT_NAME

其中：

• BUCKET_NAME 是包含要恢复的非当前版本的存储桶的名称。例如 my-bucket。
• OBJECT_NAME 是要恢复的非当前版本的名称。例如 pets/dog.png。
• GENERATION_NUMBER 是要恢复的非当前版本的世代编号，例如 1560468815691234。

如果成功，则响应类似如下示例：

Operation completed over 1 objects/58.8 KiB.

注意：某些 shell（例如启用 extendedglob 选项时的 zsh）将哈希字符 # 视为特殊字符。如果您的 shell 属于这种情况，则应使用英文单引号（在 Windows 中应使用英文双引号）将该参数括起来。

gsutil

重要提示：gsutil 不是 Cloud Storage 推荐的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

使用 gsutil cp 命令：

gsutil cp gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER gs://BUCKET_NAME/OBJECT_NAME

其中：

• BUCKET_NAME 是包含要恢复的非当前版本的存储桶的名称。例如 my-bucket。
• OBJECT_NAME 是要恢复的非当前版本的名称。例如 pets/dog.png。
• GENERATION_NUMBER 是要恢复的非当前版本的世代编号，例如 1560468815691234。

如果成功，则响应类似如下示例：

Operation completed over 1 objects/58.8 KiB.

注意：某些 shell（例如启用 extendedglob 选项时的 zsh）将哈希字符 # 视为特殊字符。如果您的 shell 属于这种情况，则应使用英文单引号（在 Windows 中应使用英文双引号）将该参数括起来。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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::move(copy).status();

  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";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

using Google.Cloud.Storage.V1;
using System;

public class CopyFileArchivedGenerationSample
{
    public Google.Apis.Storage.v1.Data.Object CopyFileArchivedGeneration(
        string sourceBucketName = "source-bucket-name",
        string sourceObjectName = "source-file",
        string destBucketName = "destination-bucket-name",
        string destObjectName = "destination-file-name",
        long? generation = 1579287380533984)
    {
        var storage = StorageClient.Create();
        var copyOptions = new CopyObjectOptions
        {
            SourceGeneration = generation
        };

        var copiedFile = storage.CopyObject(sourceBucketName, sourceObjectName,
            destBucketName, destObjectName, copyOptions);

        Console.WriteLine($"Generation {generation} of the object {sourceBucketName}/{sourceObjectName} " +
            $"was copied to to {destBucketName}/{destObjectName}.");

        return copiedFile;
    }
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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: %w", 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)

	// Optional: set a generation-match precondition to avoid potential race
	// conditions and data corruptions. The request to copy is aborted if the
	// object's generation number does not match your precondition.
	// For a dst object that does not yet exist, set the DoesNotExist precondition.
	dst = dst.If(storage.Conditions{DoesNotExist: true})
	// If the destination object already exists in your bucket, set instead a
	// generation-match precondition using its generation number.
	// attrs, err := dst.Attrs(ctx)
	// if err != nil {
	// 	return fmt.Errorf("object.Attrs: %w", err)
	// }
	// dst = dst.If(storage.Conditions{GenerationMatch: attrs.Generation})

	if _, err := dst.CopierFrom(src.Generation(gen)).Run(ctx); err != nil {
		return fmt.Errorf("Object(%q).CopierFrom(%q).Generation(%v).Run: %w", 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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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();

    // Optional: set a generation-match precondition to avoid potential race
    // conditions and data corruptions. The request returns a 412 error if the
    // preconditions are not met.
    Storage.BlobTargetOption precondition;
    if (storage.get(bucketName, newObjectName) == null) {
      // For a target object that does not yet exist, set the DoesNotExist precondition.
      // This will cause the request to fail if the object is created before the request runs.
      precondition = Storage.BlobTargetOption.doesNotExist();
    } else {
      // If the destination already exists in your bucket, instead set a generation-match
      // precondition. This will cause the request to fail if the existing object's generation
      // changes before the request runs.
      precondition =
          Storage.BlobTargetOption.generationMatch(
              storage.get(bucketName, newObjectName).getGeneration());
    }

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

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

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const srcBucketName = "your-unique-bucket-name";

// The ID of the GCS file to copy an old version of
// const srcFilename = "your-file-name";

// The generation of fileToCopy to copy
// const generation = 1579287380533984;

// The ID of the bucket to copy the file to
// const destBucketName = 'target-file-bucket';

// What to name the new file with the old data from srcFilename
// const destFileName = "your-new-file";

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

  // Optional:
  // Set a generation-match precondition to avoid potential race conditions
  // and data corruptions. The request to copy is aborted if the object's
  // generation number does not match your precondition. For a destination
  // object that does not yet exist, set the ifGenerationMatch precondition to 0
  // If the destination object already exists in your bucket, set instead a
  // generation-match precondition using its generation number.
  const copyOptions = {
    preconditionOpts: {
      ifGenerationMatch: destinationGenerationMatchPrecondition,
    },
  };

  await storage
    .bucket(srcBucketName)
    .file(srcFilename, {
      generation,
    })
    .copy(storage.bucket(destBucketName).file(destFileName), copyOptions);

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

copyOldVersionOfFile().catch(console.error);

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * Copy archived generation of a given object to a new object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectToCopy The name of the object to copy.
 *        (e.g. 'my-object')
 * @param string $generationToCopy The generation of the object to copy.
 *        (e.g. 1579287380533984)
 * @param string $newObjectName The name of the target object.
 *        (e.g. 'my-object-1579287380533984')
 */
function copy_file_archived_generation(string $bucketName, string $objectToCopy, string $generationToCopy, string $newObjectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $object = $bucket->object($objectToCopy, [
        'generation' => $generationToCopy,
    ]);

    $object->copy($bucket, [
        'name' => $newObjectName,
    ]);

    printf(
        'Generation %s of object %s in bucket %s was copied to %s',
        $generationToCopy,
        $objectToCopy,
        $bucketName,
        $newObjectName
    );
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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)

    # Optional: set a generation-match precondition to avoid potential race conditions
    # and data corruptions. The request to copy is aborted if the object's
    # generation number does not match your precondition. For a destination
    # object that does not yet exist, set the if_generation_match precondition to 0.
    # If the destination object already exists in your bucket, set instead a
    # generation-match precondition using its generation number.
    destination_generation_match_precondition = 0

    # source_generation selects a specific revision of the source object, as opposed to the latest version.
    blob_copy = source_bucket.copy_blob(
        source_blob, destination_bucket, destination_blob_name, source_generation=generation, if_generation_match=destination_generation_match_precondition
    )

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

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

def copy_file_archived_generation source_bucket_name:,
                                  source_file_name:,
                                  generation:,
                                  destination_bucket_name:,
                                  destination_file_name:
  # The ID of the bucket the original object is in
  # source_bucket_name = "source-bucket-name"

  # The ID of the GCS object to copy
  # source_file_name = "source-file-name"

  # The generation of your GCS object to copy
  # generation = 1579287380533984

  # The ID of the bucket to copy the object to
  # destination_bucket_name = "destination-bucket-name"

  # The ID of the new GCS object
  # destination_file_name = "destination-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  source_bucket = storage.bucket source_bucket_name, skip_lookup: true
  source_file = source_bucket.file source_file_name
  destination_bucket = storage.bucket destination_bucket_name, skip_lookup: true

  destination_file = source_file.copy destination_bucket, destination_file_name, generation: generation

  puts "Generation #{generation} of the file #{source_file.name} in bucket #{source_bucket.name} copied to file " \
       "#{destination_file.name} in bucket #{destination_bucket.name}"
end

REST API

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 POST Object 请求调用 JSON API：

   curl -X POST \
     -H "Authorization: Bearer OAUTH2_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"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是包含要恢复的非当前版本的存储桶的名称。例如 my-bucket。
   • OBJECT_NAME 是要恢复的非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是要恢复的非当前版本的世代编号，例如 1560468815691234。

XML API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 PUT Object 请求调用 XML API：

   curl -X PUT \
     -H "Authorization: Bearer OAUTH2_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"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是包含要恢复的非当前版本的存储桶的名称。例如 my-bucket。
   • OBJECT_NAME 是要恢复的非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是要恢复的非当前版本的世代编号，例如 1560468815691234。

恢复对象版本后，原始非当前版本仍存在于存储桶中。如果您不再需要非当前版本，可以随后将其删除或配置对象生命周期管理，以便在其符合您指定的条件时将其移除。

删除非当前对象版本

控制台

注意：Google Cloud 控制台可以列出的对象版本的数量上限为 1000 个。

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击存放所需对象的存储桶的名称。

   此时会打开“存储桶详情”页面，其中对象标签页已选中。

3. 导航到可能位于文件夹中的对象。

4. 点击所需对象的名称。

   此时会打开“对象详情”页面，其中实时对象标签页已选中。

5. 点击版本记录标签页。

6. 选中所需版本对应的复选框。

7. 点击删除按钮。

   此时会打开删除版本窗格。

8. 在文本框中输入 delete，以确认您要删除该对象。

9. 点击删除。

命令行

gcloud

使用 gcloud storage rm 命令：

gcloud storage rm gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

其中：

• BUCKET_NAME 是包含要删除的非当前版本的存储桶的名称，例如 my-bucket。
• OBJECT_NAME 是要删除的非当前版本的名称，例如 pets/dog.png。
• GENERATION_NUMBER 是要删除的非当前版本的世代编号，例如 1560468815691234。

如果成功，则响应类似如下示例：

Operation completed over 1 objects.

注意：通过使用 --all-versions 标志并省略 #GENERATION_NUMBER，您可以移除对象的所有版本（包括当前版本和非当前版本）。您可以使用 --recursive 标志移除全部对象的全部版本（可能还有存储桶本身）。

gsutil

重要提示：gsutil 不是 Cloud Storage 推荐的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

使用 gsutil rm 命令：

gsutil rm gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

其中：

• BUCKET_NAME 是包含要删除的非当前版本的存储桶的名称，例如 my-bucket。
• OBJECT_NAME 是要删除的非当前版本的名称，例如 pets/dog.png。
• GENERATION_NUMBER 是要删除的非当前版本的世代编号，例如 1560468815691234。

如果成功，则响应类似如下示例：

Operation completed over 1 objects.

注意：通过使用 -a 标志并省略 #GENERATION_NUMBER，您可以移除对象的所有版本（包括当前版本和非当前版本）。您可以使用 -r 标志移除全部对象的全部版本（可能还有存储桶本身）。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

using Google.Cloud.Storage.V1;
using System;

public class DeleteFileArchivedGenerationSample
{
    public void DeleteFileArchivedGeneration(
        string bucketName = "your-bucket-name",
        string objectName = "your-object-name",
        long? generation = 1579287380533984)
    {
        var storage = StorageClient.Create();

        storage.DeleteObject(bucketName, objectName, new DeleteObjectOptions
        {
            Generation = generation
        });

        Console.WriteLine($"Generation ${generation} of file {objectName} was deleted from bucket {bucketName}.");
    }
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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: %w", 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: %w", bucketName, objectName, gen, err)
	}
	fmt.Fprintf(w, "Generation %v of object %v was deleted from %v\n", gen, objectName, bucketName)
	return nil
}

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// The generation of fileName to delete
// const generation = 1579287380533984;

// 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);

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an archived generation of the given object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $generationToDelete the generation of the object to delete.
 *        (e.g. 1579287380533984)
 */
function delete_file_archived_generation(string $bucketName, string $objectName, string $generationToDelete): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $object = $bucket->object($objectName, [
        'generation' => $generationToDelete,
    ]);

    $object->delete();

    printf(
        'Generation %s of object %s was deleted from %s',
        $generationToDelete,
        $objectName,
        $bucketName
    );
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

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(
        f"Generation {generation} of blob {blob_name} was deleted from {bucket_name}"
    )

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

在 GitHub 上查看 反馈

def delete_file_archived_generation bucket_name:, file_name:, generation:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The generation of the file to delete
  # generation = 1579287380533984

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name, skip_lookup: true

  file = bucket.file file_name

  file.delete generation: generation

  puts "Generation #{generation} of file #{file_name} was deleted from #{bucket_name}"
end

REST API

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 DELETE Object 请求调用 JSON API：

   curl -X DELETE \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是包含要删除的非当前版本的存储桶的名称，例如 my-bucket。
   • OBJECT_NAME 是要删除的非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是要删除的非当前版本的世代编号，例如 1560468815691234。

XML API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 DELETE Object 请求调用 XML API：

   curl -X DELETE \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是包含要删除的非当前版本的存储桶的名称，例如 my-bucket。
   • OBJECT_NAME 是要删除的非当前版本的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。
   • GENERATION_NUMBER 是要删除的非当前版本的世代编号，例如 1560468815691234。

后续步骤

• 详细了解对象版本控制，包括一个深度示例。
• 对存储桶启用或停用对象版本控制。
• 了解如何使用对象生命周期管理自动管理对象版本。