Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用物件版本管理功能

本頁面說明如何啟用、停用及查看值區的物件版本管理狀態。如要瞭解如何列出、還原及刪除物件版本管理功能保留的物件，請參閱「使用版本化物件」。

必要的角色

如要取得設定及管理 bucket 物件版本管理功能所需的權限，請要求管理員為您授予 bucket 或 bucket 所在專案的 Storage 管理員 (roles/storage.admin) IAM 角色。這個預先定義的角色具備設定及管理 bucket 物件版本管理功能所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

storage.buckets.get
storage.buckets.update
storage.buckets.list
- 只有在您打算使用Google Cloud 控制台執行本頁操作說明時，才需要這項權限。

您或許還可透過自訂角色取得這些權限。

如要瞭解如何授予 bucket 角色，請參閱「在 bucket 上設定及管理 IAM 政策」。如要瞭解如何授予專案角色，請參閱「管理專案存取權」。

為 bucket 設定物件版本管理

如要啟用或停用物件版本管理功能，請在 bucket 上設定這項功能。啟用物件版本管理功能後，每當使用中的物件版本遭到取代或刪除，該版本就會變成非現行版本。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要啟用或停用物件版本管理功能的 bucket 名稱。
選取靠近頁面頂端的「保護」分頁標籤。

物件版本管理功能的目前狀態會顯示在「Object versioning」(物件版本管理) 專區。
在「Object versioning」(物件版本管理) 區段中，按一下目前狀態即可變更。

「Object versioning」(物件版本管理) 對話方塊隨即顯示。
1. 如要啟用物件版本管理功能並盡量降低儲存空間費用，請勾選「按照建議新增生命週期規則來管理版本費用」核取方塊。
按一下「確認」。

指令列

使用 gcloud storage buckets update 指令並加上適當的旗標：

gcloud storage buckets update gs://BUCKET_NAME FLAG

其中：

BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。
FLAG 為 --versioning 時，會啟用物件版本管理功能；為 --no-versioning 時，則會停用該功能。

如果成功，回應會類似以下範例：

Updating gs://my-bucket/...
  Completed 1

用戶端程式庫

C++

詳情請參閱「Cloud Storage C++ API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

以下範例會為值區啟用物件版本管理功能：

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

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

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

以下範例會停用值區的物件版本管理功能：

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

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

  auto versioning =
      patched->versioning().value_or(gcs::BucketVersioning{false});
  std::cout << "Object versioning for bucket " << bucket_name << " is "
            << (versioning.enabled ? "enabled" : "disabled") << "\n";
}

C#

詳情請參閱 Cloud Storage C# API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

以下範例會為值區啟用物件版本管理功能：


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketEnableVersioningSample
{
	public Bucket BucketEnableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning == null)
		{
			bucket.Versioning = new Bucket.VersioningData();
		}
		bucket.Versioning.Enabled = true;

		bucket = storage.UpdateBucket(bucket);
		Console.WriteLine($"Versioning is now enabled for bucket {bucketName}.");
		return bucket;
	}
}

以下範例會停用值區的物件版本管理功能：


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketDisableVersioningSample
{
	public Bucket BucketDisableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning?.Enabled != true)
		{
			Console.WriteLine($"Versioning already disabled for bucket {bucketName}.");
		}
		else
		{
        	    bucket.Versioning.Enabled = false;

		    bucket = storage.UpdateBucket(bucket);
                    Console.WriteLine($"Versioning is now disabled for bucket {bucketName}.");
                }
		return bucket;
	}
}

Go

詳情請參閱「Cloud Storage Go API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會為值區啟用物件版本管理功能：

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: %w", 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: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was enabled for %v\n", bucketName)
	return nil
}

以下範例會停用值區的物件版本管理功能：

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: %w", 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: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was disabled for %v\n", bucketName)
	return nil
}

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會為值區啟用物件版本管理功能：

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

下列範例會停用值區的物件版本管理功能：

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

詳情請參閱 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 enableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: true,
    },
  });

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

enableBucketVersioning().catch(console.error);

以下範例會停用值區的物件版本管理功能：

/**
 * 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 disableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: false,
    },
  });

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

disableBucketVersioning().catch(console.error);

PHP

詳情請參閱「Cloud Storage PHP API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

以下範例會為值區啟用物件版本管理功能：

use Google\Cloud\Storage\StorageClient;

/**
 * Enable versioning on the specified bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function enable_versioning(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => true,
        ]
    ]);

    printf('Versioning is now enabled for bucket %s', $bucketName);
}

以下範例會停用值區的物件版本管理功能：

use Google\Cloud\Storage\StorageClient;

/**
 * Disable versioning of the given bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function disable_versioning(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => false,
        ]
    ]);

    printf('Versioning is now disabled for bucket %s', $bucketName);
}

Python

詳情請參閱「Cloud Storage Python API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會為值區啟用物件版本管理功能：

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(f"Versioning was enabled for bucket {bucket.name}")
    return bucket

下列範例會停用值區的物件版本管理功能：

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(f"Versioning was disabled for bucket {bucket}")
    return bucket

Ruby

詳情請參閱「Cloud Storage Ruby API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會為值區啟用物件版本管理功能：

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

下列範例會停用值區的物件版本管理功能：

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

Rust

以下範例會為值區啟用物件版本管理功能：

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::bucket::Versioning;
use google_cloud_wkt::FieldMask;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let bucket = client
        .get_bucket()
        .set_name(format!("projects/_/buckets/{bucket_id}"))
        .send()
        .await?;
    let metageneration = bucket.metageneration;
    let bucket = client
        .update_bucket()
        .set_bucket(bucket.set_versioning(Versioning::new().set_enabled(true)))
        .set_if_metageneration_match(metageneration)
        .set_update_mask(FieldMask::default().set_paths(["versioning"]))
        .send()
        .await?;
    println!("Versioning enabled for bucket {bucket_id}: {bucket:?}");
    Ok(())
}

以下範例會停用值區的物件版本管理功能：

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::bucket::Versioning;
use google_cloud_wkt::FieldMask;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let bucket = client
        .get_bucket()
        .set_name(format!("projects/_/buckets/{bucket_id}"))
        .send()
        .await?;
    let metageneration = bucket.metageneration;
    let bucket = client
        .update_bucket()
        .set_bucket(bucket.set_versioning(Versioning::new().set_enabled(false)))
        .set_if_metageneration_match(metageneration)
        .set_update_mask(FieldMask::default().set_paths(["versioning"]))
        .send()
        .await?;
    println!("Versioning disabled for bucket {bucket_id}: {bucket:?}");
    Ok(())
}

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
建立包含下列資訊的 JSON 檔案：
```
{
  "versioning": {
    "enabled": STATE
  }
}
```
其中 STATE 為 true 或 false。

使用 cURL 來透過 PATCH 值區要求呼叫 JSON API：

curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"

其中：

JSON_FILE_NAME 是您在步驟 2 建立的 JSON 檔案路徑。
BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。

XML API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含下列資訊的 XML 檔案：

<VersioningConfiguration>
  <Status>STATE</Status>
</VersioningConfiguration>

其中 STATE 為 Enabled 或 Suspended。

使用 cURL 呼叫 XML API，並提供 PUT Bucket 要求和 versioning 查詢字串參數：
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?versioning"
```
其中：
- XML_FILE_NAME 是您在步驟 2 建立的 XML 檔案路徑。
- BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。

檢查是否已啟用物件版本管理

如要檢查值區是否已啟用物件版本管理功能，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在值區清單中，每個值區的物件版本管理狀態會顯示在「Protection」(保護) 欄中。

啟用後，系統會顯示「物件版本管理」文字。

指令列

使用 gcloud storage buckets describe 指令搭配 --format 旗標：

gcloud storage buckets describe gs://BUCKET_NAME --format="default(versioning_enabled)"

其中 BUCKET_NAME 是要查看狀態的 bucket 名稱。例如：my-bucket。

如果成功且已啟用物件版本管理，回應內容會與下列範例類似：

versioning:
  enabled: true

如果成功且未啟用物件版本管理功能，回應會與下列範例相似：

null

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

使用 cURL 來透過 GET 值區要求呼叫 JSON API：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"

其中 BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。

如果成功且已啟用物件版本管理，回應內容會與下列範例類似：

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

如果成功且未啟用物件版本管理功能，回應會與下列範例相似：

{}

XML API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 呼叫 XML API，並提供 GET Bucket 要求和 versioning 查詢字串參數：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?versioning"
```
其中 BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。

如果成功且已啟用物件版本管理，回應內容會與下列範例類似：

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

如果成功且未啟用物件版本管理功能，回應會與下列範例類似：

<VersioningConfiguration/>

後續步驟

進一步瞭解物件版本管理。
瞭解如何使用非現行物件。
瞭解如何使用物件生命週期管理功能，自動管理物件版本。
瞭解如何使用要求前置條件，避免競爭狀況。

使用物件版本管理功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要的角色

所需權限

為 bucket 設定物件版本管理

控制台

指令列

用戶端程式庫

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

REST API

JSON API

XML API

檢查是否已啟用物件版本管理

控制台

指令列

REST API

JSON API

XML API

後續步驟

使用物件版本管理功能