使用具有版本控制的对象

概览 设置

本页面介绍如何列出、访问、恢复和删除非当前对象,这通常适用于启用对象版本控制的存储分区。 非当前对象也称为采用版本控制的对象。

准备工作

如需处理非当前对象,请完成以下前提步骤。

启用对象版本控制

如果您尚未在存储桶上启用对象版本控制,请予以启用。

获取所需角色

如需获得管理非当前对象所需的权限,请让管理员向您授予项目的 Storage Object User (roles/storage.objectUser) IAM 角色。此预定义角色包含管理非当前对象所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list

您也可以使用自定义角色来获取这些权限。

如需了解如何授予项目的角色,请参阅管理对项目的访问权限

根据您的使用场景,您可能需要更多权限或其他角色:

  • 如果您计划使用 Google Cloud 控制台执行本页面上的任务,则还需要 storage.buckets.list 权限,Storage Object User (roles/storage.objectUser) 角色不提供此权限。如需获得此权限,请让您的管理员为您授予项目的 Storage Admin (roles/storage.admin) 角色。

  • 如果为存储桶停用了统一存储桶级访问权限,则在以下情况下,您还需要其他权限:

    • 如果您计划返回非当前对象及其 ACL,则还需要 storage.objects.getIamPolicy 权限,该权限未包含在 Storage Object User (roles/storage.objectUser) 角色中。如需获得此权限,请让管理员为您授予项目的 Storage Object Admin (roles/storage.objectAdmin) 角色。

    • 如果您计划重命名或恢复具有 ACL 的非当前对象,则还需要 storage.objects.setIamPolicy 权限,该权限未包含在 Storage Object User (roles/storage.objectUser) 角色中。如需获得此权限,请让管理员为您授予项目的 Storage Object Admin (roles/storage.objectAdmin) 角色。

列出非当前对象版本

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

控制台

  1. 在 Google Cloud 控制台中,转到 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中,点击包含所需对象的存储桶的名称。

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

  3. 如需查看非当前对象,请点击显示下拉菜单,然后选择当前对象和非当前对象

  4. 在对象列表中,点击要查看其版本的对象的名称。

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

  5. 点击版本历史记录标签页以查看对象的所有版本。

命令行

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

客户端库

C++

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

如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证


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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

/**
 * 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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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. 安装并初始化 gcloud CLI,以便为 Authorization 标头生成访问令牌。

  2. 使用 cURL,通过 Objects: list 请求调用 JSON API

    curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://storage./storage/v1/b/BUCKET_NAME/o?versions=true"

    其中 BUCKET_NAME 是包含对象的存储桶的名称。例如 my-bucket

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

XML API

  1. 安装并初始化 gcloud CLI,以便为 Authorization 标头生成访问令牌。

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

    curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://storage./BUCKET_NAME?versions&list-type=2"

    其中 BUCKET_NAME 是包含对象的存储桶的名称。例如 my-bucket

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

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

访问非当前对象版本

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

控制台

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

命令行

  1. 将非当前版本的世代编号附加到对象名称:

    OBJECT_NAME#GENERATION_NUMBER

    其中:

    • OBJECT_NAME 是非当前版本的名称,例如 pets/dog.png
    • GENERATION_NUMBER 是非当前版本的世代编号,例如 1560468815691234
  2. 使用上一步中的字符串,按照对象现行版本的正常方式继续操作。例如,如需查看非当前对象版本的元数据,请使用 gcloud storage objects describe 命令:

    gcloud storage objects describe gs://my-bucket/pets/dog.png#1560468815691234

REST API

JSON API

  1. 将非当前版本的世代编号附加到对象的 URI:

    https://storage./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. 使用上一步中的 URI,按照对象现行版本的正常方式继续操作。例如,如需查看非当前对象版本的元数据,请使用 cURL对象:获取请求中调用 JSON API

    curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://storage./storage/v1/b/my-bucket/o/pets/dog.png?generation=1560468815691234"

XML API

  1. 将非当前版本的世代编号附加到对象的 URI:

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

    其中:

    • BUCKET_NAME 是包含非当前版本的存储桶的名称,例如 my-bucket
    • OBJECT_NAME 是非当前版本的网址编码名称。例如,pets/dog.png 的网址编码为 pets%2Fdog.png
    • GENERATION_NUMBER 是非当前版本的世代编号,例如 1560468815691234
  2. 使用上一步中的 URI,按照对象现行版本的正常方式继续操作。例如,如需查看非当前对象版本的元数据,请使用 cURLHEAD 对象请求中调用 XML API

    curl -I GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://storage./my-bucket/pets/dog.png?generation=1560468815691234"

恢复非当前对象版本

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

控制台

  1. 在 Google Cloud 控制台中,转到 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中,点击包含所需对象的存储桶的名称。

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

  3. 如需查看非当前对象,请点击显示下拉菜单,然后选择当前对象和非当前对象

  4. 在对象列表中,点击要恢复的对象版本的名称。

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

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

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

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

  7. 点击确认

命令行

使用 gcloud storage cp 命令:

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

其中:

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

如果成功,则响应类似如下示例:

Operation completed over 1 objects/58.8 KiB.

客户端库

C++

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

如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证

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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证


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 =