启用和使用对象保留配置

本页面介绍如何使用对象保留锁定功能，包括为存储桶启用该功能，以及为存储桶内的对象设置保留配置。

所需的角色

如需获得为存储桶启用对象保留锁定功能以及为对象设置保留配置所需的权限，请让您的管理员为您授予存储桶或存储桶所属项目的 Storage Admin (roles/storage.admin) IAM 角色。此预定义角色包含设置和管理保留配置所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

storage.buckets.create
storage.buckets.enableObjectRetention
storage.buckets.get
storage.buckets.list
- 仅当您计划使用Google Cloud 控制台执行本页面上的任务时，才需要此权限。
storage.objects.get
storage.objects.list
- 仅当您计划使用Google Cloud 控制台执行本页面上的任务时，才需要此权限。
storage.objects.overrideUnlockedRetention
- 只有在您计划锁定或缩短现有保留配置时，才需要此权限。
storage.objects.setRetention
storage.objects.update

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

如需了解如何授予存储桶的角色，请参阅设置和管理存储桶的 IAM 政策。如需了解如何授予项目的角色，请参阅管理对项目的访问权限。

为存储桶启用对象保留

按照以下说明为存储桶中的对象启用保留配置。如果您想为现有存储桶启用对象保留配置，则必须按照 Google Cloud 控制台说明进行操作。

控制台

如需为新存储桶启用对象保留配置，请执行以下操作：

按照正常方式创建存储桶，在选择如何保护对象数据步骤中，选择保留（针对合规性），然后启用对象保留。

如需为现有存储桶启用对象保留配置，请执行以下操作：

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

进入“存储桶”
在存储桶列表中，点击要启用对象保留功能的存储桶的名称。
选择页面顶部附近的保护标签页。

存储桶的对象保留状态显示在对象保留部分中。
在对象保留部分，点击未启用对象保留。
在显示的对话框中，点击确认。

命令行

按照正常方式创建存储桶，并在命令中添加 --enable-per-object-retention 标志。

客户端库

C++

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

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

//! [create-bucket-with-object-retention]
namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& project_id) {
  auto bucket = client.CreateBucket(bucket_name, gcs::BucketMetadata{},
                                    gcs::EnableObjectRetention(true),
                                    gcs::OverrideDefaultProject(project_id));
  if (!bucket) throw std::move(bucket).status();

  if (!bucket->has_object_retention()) {
    throw std::runtime_error("missing object retention in new bucket");
  }
  std::cout << "Successfully created bucket " << bucket_name
            << " with object retention: " << bucket->object_retention()
            << "\n";
}
//! [create-bucket-with-object-retention]

C#

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

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


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

public class CreateBucketWithObjectRetentionSample
{
    public Bucket CreateBucketWithObjectRetention(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.CreateBucket(projectId, bucketName, new CreateBucketOptions
        {
            ObjectRetentionEnabled = true
        });
        Console.WriteLine($"Created {bucketName}, with Object Retention enabled.");
        return bucket;
    }
}

Java

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

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


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

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

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Bucket bucket =
        storage.create(
            BucketInfo.of(bucketName), Storage.BucketTargetOption.enableObjectRetention(true));

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " with object retention enabled setting: "
            + bucket.getObjectRetention().getMode().toString());
  }
}

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
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithObjectRetention() {
  const [bucket] = await storage.createBucket(bucketName, {
    enableObjectRetention: true,
  });

  console.log(
    `Created '${bucket.name}' with object retention enabled setting: ${bucket.metadata.objectRetention.mode}`
  );
}

createBucketWithObjectRetention().catch(console.error);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Create a Cloud Storage bucket with the object retention enabled.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_with_object_retention(string $bucketName): void
{
    $storage = new StorageClient();

    $bucket = $storage->createBucket($bucketName, [
        'enableObjectRetention' => true
    ]);
    printf(
        'Created bucket %s with object retention enabled setting: %s' . PHP_EOL,
        $bucketName,
        $bucket->info()['objectRetention']['mode']
    );
}

Python

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

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

from google.cloud import storage


def create_bucket_object_retention(bucket_name):
    """Creates a bucket with object retention enabled."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.create_bucket(bucket_name, enable_object_retention=True)

    print(f"Created bucket {bucket_name} with object retention enabled setting: {bucket.object_retention_mode}")

REST API

JSON API

按照正常方式创建存储桶，并在请求中添加查询参数 enableObjectRetention=true。

XML API

按照正常方式创建存储桶，并在请求中添加标头 x-goog-bucket-object-lock-enabled: True。

查看存储桶的对象保留状态

如需查看是否可以为存储桶中的对象设置保留配置，请执行以下操作：

控制台

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

进入“存储桶”
点击您要查看其状态的存储桶的名称。
点击保护标签页。
存储桶的对象保留状态显示在对象保留部分中。

命令行

使用带有 --format 标志的 gcloud storage buckets describe 命令：

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

其中 BUCKET_NAME 是您要查看保留政策的存储桶的名称。例如 my-bucket。

如果成功并且存储桶存在保留政策，则响应类似于以下内容：

per_object_retention:
  mode: Enabled

如果成功且存储桶不存在保留政策，则响应类似于以下内容：

null

客户端库

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> bucket_metadata =
      client.GetBucketMetadata(bucket_name);
  if (!bucket_metadata) throw std::move(bucket_metadata).status();

  std::cout << "The metadata for bucket " << bucket_metadata->name() << " is "
            << *bucket_metadata << "\n";
}

C#

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

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

如需查看存储桶的对象保留配置，请按照显示存储桶的元数据的说明操作，并在响应中查找对象保留字段。


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

public class GetBucketMetadataSample
{
    public Bucket GetBucketMetadata(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{bucket.Name}");
        Console.WriteLine($"Acl:\t{bucket.Acl}");
        Console.WriteLine($"Billing:\t{bucket.Billing}");
        Console.WriteLine($"Cors:\t{bucket.Cors}");
        Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
        Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
        Console.WriteLine($"Encryption:\t{bucket.Encryption}");
        if (bucket.Encryption != null)
        {
            Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
        }
        Console.WriteLine($"Id:\t{bucket.Id}");
        Console.WriteLine($"Kind:\t{bucket.Kind}");
        Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
        Console.WriteLine($"Location:\t{bucket.Location}");
        Console.WriteLine($"LocationType:\t{bucket.LocationType}");
        Console.WriteLine($"Logging:\t{bucket.Logging}");
        Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
        Console.WriteLine($"ObjectRetention:\t{bucket.ObjectRetention}");
        Console.WriteLine($"Owner:\t{bucket.Owner}");
        Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
        Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
        Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
        Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
        Console.WriteLine($"Updated:\t{bucket.Updated}");
        Console.WriteLine($"Versioning:\t{bucket.Versioning}");
        Console.WriteLine($"Website:\t{bucket.Website}");
        Console.WriteLine($"TurboReplication:\t{bucket.Rpo}");
        if (bucket.Labels != null)
        {
            Console.WriteLine("Labels:");
            foreach (var label in bucket.Labels)
            {
                Console.WriteLine($"{label.Key}:\t{label.Value}");
            }
        }
        return bucket;
    }
}

Java

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

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

如需查看存储桶的对象保留配置，请按照显示存储桶的元数据的说明操作，并在响应中查找对象保留字段。


import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetBucketMetadata {
  public static void getBucketMetadata(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();

    // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
    Bucket bucket =
        storage.get(bucketName, Storage.BucketGetOption.fields(Storage.BucketField.values()));

    // Print bucket metadata
    System.out.println("BucketName: " + bucket.getName());
    System.out.println("DefaultEventBasedHold: " + bucket.getDefaultEventBasedHold());
    System.out.println("DefaultKmsKeyName: " + bucket.getDefaultKmsKeyName());
    System.out.println("Id: " + bucket.getGeneratedId());
    System.out.println("IndexPage: " + bucket.getIndexPage());
    System.out.println("Location: " + bucket.getLocation());
    System.out.println("LocationType: " + bucket.getLocationType());
    System.out.println("Metageneration: " + bucket.getMetageneration());
    System.out.println("NotFoundPage: " + bucket.getNotFoundPage());
    System.out.println("RetentionEffectiveTime: " + bucket.getRetentionEffectiveTime());
    System.out.println("RetentionPeriod: " + bucket.getRetentionPeriod());
    System.out.println("RetentionPolicyIsLocked: " + bucket.retentionPolicyIsLocked());
    System.out.println("RequesterPays: " + bucket.requesterPays());
    System.out.println("SelfLink: " + bucket.getSelfLink());
    System.out.println("StorageClass: " + bucket.getStorageClass().name());
    System.out.println("TimeCreated: " + bucket.getCreateTime());
    System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
    System.out.println("ObjectRetention: " + bucket.getObjectRetention());
    if (bucket.getLabels() != null) {
      System.out.println("\n\n\nLabels:");
      for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
        System.out.println(label.getKey() + "=" + label.getValue());
      }
    }
    if (bucket.getLifecycleRules() != null) {
      System.out.println("\n\n\nLifecycle Rules:");
      for (BucketInfo.LifecycleRule rule : bucket.getLifecycleRules()) {
        System.out.println(rule);
      }
    }
  }
}

Node.js

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

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

如需查看存储桶的对象保留配置，请按照显示存储桶的元数据的说明操作，并在响应中查找对象保留字段。

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

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

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

  // Get Bucket Metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  console.log(JSON.stringify(metadata, null, 2));
}

PHP

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

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

如需查看存储桶的对象保留配置，请按照显示存储桶的元数据的说明操作，并在响应中查找对象保留字段。

use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function get_bucket_metadata(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();

    printf('Bucket Metadata: %s' . PHP_EOL, print_r($info, true));
}

Python

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

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

如需查看存储桶的对象保留配置，请按照显示存储桶的元数据的说明操作，并在响应中查找对象保留字段。


from google.cloud import storage


def bucket_metadata(bucket_name):
    """Prints out a bucket's metadata."""
    # bucket_name = 'your-bucket-name'

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    print(f"ID: {bucket.id}")
    print(f"Name: {bucket.name}")
    print(f"Storage Class: {bucket.storage_class}")
    print(f"Location: {bucket.location}")
    print(f"Location Type: {bucket.location_type}")
    print(f"Cors: {bucket.cors}")
    print(f"Default Event Based Hold: {bucket.default_event_based_hold}")
    print(f"Default KMS Key Name: {bucket.default_kms_key_name}")
    print(f"Metageneration: {bucket.metageneration}")
    print(
        f"Public Access Prevention: {bucket.iam_configuration.public_access_prevention}"
    )
    print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
    print(f"Retention Period: {bucket.retention_period}")
    print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
    print(f"Object Retention Mode: {bucket.object_retention_mode}")
    print(f"Requester Pays: {bucket.requester_pays}")
    print(f"Self Link: {bucket.self_link}")
    print(f"Time Created: {bucket.time_created}")
    print(f"Versioning Enabled: {bucket.versioning_enabled}")
    print(f"Labels: {bucket.labels}")

REST API

JSON API

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

使用 cURL，通过包含 objectRetention 字段的 GET Bucket 请求调用 JSON API：

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

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

XML API

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

使用 cURL 通过范围限定为 ?object-lock 的 GET Bucket 请求调用 XML API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?object-lock"
```
其中 BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

设置对象的保留配置

如需为对象设置保留配置，对象必须存储在启用了对象保留的存储桶中。如需为对象设置保留配置，请执行以下操作：

控制台

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

进入“存储桶”
在存储桶列表中，找到包含要设置或修改其保留配置的对象的存储桶，并点击其名称。

此时会打开“存储桶详情”页面，其中“对象”标签页已选中。
找到到可能位于文件夹中的对象。
点击对象的名称。

此时会打开对象详情页面，其中显示对象元数据。
在保护部分中，点击与来自对象保留配置关联的修改图标 ()。

系统会打开修改保留窗格。
在对象保留期限配置部分中，点击已启用或已停用。
1. 如果已启用保留配置，请在保留到特定时间部分中为配置选择日期和时间，然后在保留模式部分中点击解锁或锁定。
点击确认。

命令行

使用带有相应标志的 gcloud storage objects update 命令。如需添加或修改保留配置，请使用以下命令。请注意，如果您通过锁定现有配置或缩短其“保留到特定时间”的方式来修改现有配置，则还必须额外添加 --override-unlocked-retention 标志：

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --retain-until=DATETIME --retention-mode=STATE

其中：

BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
OBJECT_NAME 是相关对象的名称，例如 kitten.png。
DATETIME 是可以删除对象的最早日期和时间。例如 2028-02-15T05:30:00Z。
STATE 是 Locked 或 Unlocked。

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

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

如需从对象中移除保留配置，请使用以下命令：

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --clear-retention --override-unlocked-retention

其中：

BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
OBJECT_NAME 是相关对象的名称，例如 kitten.png。

客户端库

C++

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

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

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  auto original = client.GetObjectMetadata(bucket_name, object_name);
  if (!original) throw std::move(original).status();

  auto const until =
      std::chrono::system_clock::now() + std::chrono::hours(24);
  auto updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetRetention(
          gcs::ObjectRetention{gcs::ObjectRetentionUnlocked(), until}),
      gcs::OverrideUnlockedRetention(true),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!updated) throw std::move(updated).status();

  std::cout << "Successfully updated object retention configuration: "
            << *updated << "\n";
}

C#

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

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


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

public class SetObjectRetentionPolicySample
{
    public Google.Apis.Storage.v1.Data.Object SetObjectRetentionPolicy(
        string bucketName = "your-unique-bucket-name", // A bucket that has object retention enabled
        string objectName = "your-object-name") // An object that does not have a retention policy set
    {
        var storage = StorageClient.Create();
        var file = storage.GetObject(bucketName, objectName);


        file.Retention = new Object.RetentionData
        {
            Mode = "Unlocked", RetainUntilTimeDateTimeOffset = DateTimeOffset.UtcNow.AddDays(10)
        };

        file = storage.UpdateObject(file);

        Console.WriteLine($"The retention policy for object {objectName} was set to:");
        Console.WriteLine("Mode: " + file.Retention.Mode);
        Console.WriteLine("RetainUntilTime: " + file.Retention.RetainUntilTimeDateTimeOffset.ToString());

        // To modify an existing policy on an Unlocked object, pass in the override parameter
        file.Retention = new Object.RetentionData
        {
            Mode = "Unlocked", RetainUntilTimeDateTimeOffset = DateTimeOffset.UtcNow.AddDays(9)
        };

        file = storage.UpdateObject(file, new UpdateObjectOptions { OverrideUnlockedRetention = true });

        Console.WriteLine($"The retention policy for object {objectName} was updated to:");
        Console.WriteLine("Mode: " + file.Retention.Mode);
        Console.WriteLine("RetainUntilTime: " + file.Retention.RetainUntilTimeDateTimeOffset.ToString());

        return file;
    }
}

Java

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

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


import static java.time.OffsetDateTime.now;

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo.Retention;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;

public class SetObjectRetentionPolicy {
  public static void setObjectRetentionPolicy(
      String projectId, String bucketName, String objectName) throws StorageException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket that has object retention enabled
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    Blob blob = storage.get(blobId);
    if (blob == null) {
      System.out.println("The object " + objectName + " was not found in " + bucketName);
      return;
    }

    Blob updated =
        blob.toBuilder()
            .setRetention(
                Retention.newBuilder()
                    .setMode(Retention.Mode.UNLOCKED)
                    .setRetainUntilTime(now().plusDays(10))
                    .build())
            .build()
            .update();

    System.out.println("Retention policy for object " + objectName + " was set to:");
    System.out.println(updated.getRetention().toString());

    // To modify an existing policy on an Unlocked object, pass in the override parameter
    blob.toBuilder()
        .setRetention(
            updated.getRetention().toBuilder().setRetainUntilTime(now().plusDays(9)).build())
        .build()
        .update(Storage.BlobTargetOption.overrideUnlockedRetention(true));

    System.out.println("Retention policy for object " + objectName + " was updated to:");
    System.out.println(storage.get(blobId).getRetention().toString());
  }
}

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

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

// The content to be uploaded in the GCS file
// const contents = 'your file content';

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function setObjectRetentionPolicy() {
  // Get a reference to the bucket
  const myBucket = storage.bucket(bucketName);

  // Create a reference to a file object
  const file = myBucket.file(destFileName);

  // Save the file data
  await file.save(contents);

  // Set the retention policy for the file
  const retentionDate = new Date();
  retentionDate.setDate(retentionDate.getDate() + 10);
  const [metadata] = await file.setMetadata({
    retention: {
      mode: 'Unlocked',
      retainUntilTime: retentionDate.toISOString(),
    },
  });

  console.log(
    `Retention policy for file ${file.name} was set to: ${metadata.retention.mode}`
  );

  // To modify an existing policy on an unlocked file object, pass in the override parameter
  const newRetentionDate = new Date(retentionDate.getDate());
  newRetentionDate.setDate(newRetentionDate.getDate() + 9);
  const [newMetadata] = await file.setMetadata({
    retention: {
      mode: 'Unlocked',
      retainUntilTime: newRetentionDate,
    },
    overrideUnlockedRetention: true,
  });

  console.log(
    `Retention policy for file ${file.name} was updated to: ${newMetadata.retention.retainUntilTime}`
  );
}

setObjectRetentionPolicy().catch(console.error);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a bucket's retention policy.
 *
 * @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')
 */
function set_object_retention_policy(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $expires = (new \DateTime)->add(
        \DateInterval::createFromDateString('+10 days')
    );
    // To modify an existing policy on an Unlocked object, pass the override parameter
    $object->update([
        'retention' => [
            'mode' => 'Unlocked',
            'retainUntilTime' => $expires->format(\DateTime::RFC3339)
        ],
        'overrideUnlockedRetention' => true
    ]);
    printf(
        'Retention policy for object %s was updated to: %s' . PHP_EOL,
        $objectName,
        $object->info()['retention']['retainUntilTime']
    );
}

Python

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

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

from google.cloud import storage


def set_object_retention_policy(bucket_name, contents, destination_blob_name):
    """Set the object retention policy of a file."""

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The contents to upload to the file
    # contents = "these are my contents"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)
    blob.upload_from_string(contents)

    # Set the retention policy for the file.
    blob.retention.mode = "Unlocked"
    retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=10)
    blob.retention.retain_until_time = retention_date
    blob.patch()
    print(
        f"Retention policy for file {destination_blob_name} was set to: {blob.retention.mode}."
    )

    # To modify an existing policy on an unlocked file object, pass in the override parameter.
    new_retention_date = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=9)
    blob.retention.retain_until_time = new_retention_date
    blob.patch(override_unlocked_retention=True)
    print(
        f"Retention policy for file {destination_blob_name} was updated to: {blob.retention.retain_until_time}."
    )

REST API

JSON API

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

创建一个包含以下信息的 JSON 文件：

{
  "retention": {
    "mode": STATE,
    "retainUntilTime": "DATETIME"
  }
}

其中：

STATE 是 Locked 或 Unlocked。
DATETIME 是可以删除对象的最早日期和时间。例如 2028-02-15T05:30:00Z。

使用 cURL，通过 PATCH Object 请求调用 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/o/OBJECT_NAME?overrideUnlockedRetention=BOOLEAN"
```
其中：
- JSON_FILE_NAME 是您在第 2 步中创建的文件的路径。
- BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
- OBJECT_NAME 是相关对象的网址编码名称。例如，pets/kitten.png 的网址编码为 pets%2Fkitten.png。
- 如果请求缩短、移除或锁定现有的保留配置，则 BOOLEAN 必须为 true。否则，您可以从请求中完全排除 overrideUnlockedRetention 参数。

XML API

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

创建一个包含以下信息的 XML 文件：

<Retention>
  <Mode>
    STATE
  </Mode>
  <RetainUntilDate>
    DATETIME
  </RetainUntilDate>
</Retention>

其中：

STATE 是 GOVERNANCE 或 COMPLIANCE。
DATETIME 是可以删除对象的最早日期和时间。例如 2028-02-15T05:30:00Z。

使用 cURL 通过范围限定为 ?retention 的 PUT Object 请求调用 XML API：
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-bypass-governance-retention: BOOLEAN" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"
```
其中：
- XML_FILE_NAME 是您在第 2 步中创建的 XML 文件的路径。
- 如果请求缩短、移除或锁定现有的保留配置，则 BOOLEAN 必须为 true。否则，您可以从请求中完全排除 x-goog-bypass-governance-retention 标头。
- BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
- OBJECT_NAME 是相关对象的网址编码名称。例如，pets/kitten.png 的网址编码为 pets%2Fkitten.png。

查看对象的保留配置

如需查看对象上设置的保留配置（如果有），请执行以下操作：

控制台

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

进入“存储桶”
在存储桶列表中，找到包含要查看其保留配置的对象的存储桶，并点击其名称。

此时会打开“存储桶详情”页面，其中“对象”标签页已选中。
找到到可能位于文件夹中的对象。
点击对象的名称。

此时会打开对象详情页面，其中显示对象元数据。对象的任何保留配置的相关信息都会显示在保护部分中。

命令行

使用带有 --format 标志的 gcloud storage objects describe 命令：

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(retention_settings)"

其中：

BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
OBJECT_NAME 是相关对象的名称，例如 kitten.png。

如果成功并且对象有保留配置，则响应类似于以下内容：

retention_settings:
  mode: Unlocked
  retainUntilTime: '2028-11-30T14:11:14+00:00'

如果成功且对象没有保留配置，则响应类似于以下内容：

null

客户端库

C++

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

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

如需查看对象的保留配置，请按照显示对象的元数据的说明操作，并在响应中查找保留字段。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> object_metadata =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!object_metadata) throw std::move(object_metadata).status();

  std::cout << "The metadata for object " << object_metadata->name()
            << " in bucket " << object_metadata->bucket() << " is "
            << *object_metadata << "\n";
}

C#

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

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

如需查看对象的保留配置，请按照显示对象的元数据的说明操作，并在响应中查找保留字段。


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

public class GetMetadataSample
{
    public Google.Apis.Storage.v1.Data.Object GetMetadata(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{storageObject.Bucket}");
        Console.WriteLine($"CacheControl:\t{storageObject.CacheControl}");
        Console.WriteLine($"ComponentCount:\t{storageObject.ComponentCount}");
        Console.WriteLine($"ContentDisposition:\t{storageObject.ContentDisposition}");
        Console.WriteLine($"ContentEncoding:\t{storageObject.ContentEncoding}");
        Console.WriteLine($"ContentLanguage:\t{storageObject.ContentLanguage}");
        Console.WriteLine($"ContentType:\t{storageObject.ContentType}");
        Console.WriteLine($"Crc32c:\t{storageObject.Crc32c}");
        Console.WriteLine($"ETag:\t{storageObject.ETag}");
        Console.WriteLine($"Generation:\t{storageObject.Generation}");
        Console.WriteLine($"Id:\t{storageObject.Id}");
        Console.WriteLine($"Kind:\t{storageObject.Kind}");
        Console.WriteLine($"KmsKeyName:\t{storageObject.KmsKeyName}");
        Console.WriteLine($"Md5Hash:\t{storageObject.Md5Hash}");
        Console.WriteLine($"MediaLink:\t{storageObject.MediaLink}");
        Console.WriteLine($"Metageneration:\t{storageObject.Metageneration}");
        Console.WriteLine($"Name:\t{storageObject.Name}");
        Console.WriteLine($"Retention:\t{storageObject.Retention}");
        Console.WriteLine($"Size:\t{storageObject.Size}");
        Console.WriteLine($"StorageClass:\t{storageObject.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{storageObject.TimeCreated}");
        Console.WriteLine($"Updated:\t{storageObject.Updated}");
        bool eventBasedHold = storageObject.EventBasedHold ?? false;
        Console.WriteLine("Event-based hold enabled? {0}", eventBasedHold);
        bool temporaryHold = storageObject.TemporaryHold ?? false;
        Console.WriteLine("Temporary hold enabled? {0}", temporaryHold);
        Console.WriteLine($"RetentionExpirationTime\t{storageObject.RetentionExpirationTime}");
        if (storageObject.Metadata != null)
        {
            Console.WriteLine("Metadata: ");
            foreach (var metadata in storageObject.Metadata)
            {
                Console.WriteLine($"{metadata.Key}:\t{metadata.Value}");
            }
        }
        Console.WriteLine($"CustomTime:\t{storageObject.CustomTime}");
        return storageObject;
    }
}

Java

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

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

如需查看对象的保留配置，请按照显示对象的元数据的说明操作，并在响应中查找保留字段。


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;
import java.util.Date;
import java.util.Map;

public class GetObjectMetadata {
  public static void getObjectMetadata(String projectId, String bucketName, String blobName)
      throws StorageException {
    // 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";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // Select all fields
    // Fields can be selected individually e.g. Storage.BlobField.CACHE_CONTROL
    Blob blob =
        storage.get(bucketName, blobName, Storage.BlobGetOption.fields(Storage.BlobField.values()));

    // Print blob metadata
    System.out.println("Bucket: " + blob.getBucket());
    System.out.println("CacheControl: " + blob.getCacheControl());
    System.out.println("ComponentCount: " + blob.getComponentCount());
    System.out.println("ContentDisposition: " + blob.getContentDisposition());
    System.out.println("ContentEncoding: " + blob.getContentEncoding());
    System.out.println("ContentLanguage: " + blob.getContentLanguage());
    System.out.println("ContentType: " + blob.getContentType());
    System.out.println("CustomTime: " + blob.getCustomTime());
    System.out.println("Crc32c: " + blob.getCrc32c());
    System.out.println("Crc32cHexString: " + blob.getCrc32cToHexString());
    System.out.println("ETag: " + blob.getEtag());
    System.out.println("Generation: " + blob.getGeneration());
    System.out.println("Id: " + blob.getBlobId());
    System.out.println("KmsKeyName: " + blob.getKmsKeyName());
    System.out.println("Md5Hash: " + blob.getMd5());
    System.out.println("Md5HexString: " + blob.getMd5ToHexString());
    System.out.println("MediaLink: " + blob.getMediaLink());
    System.out.println("Metageneration: " + blob.getMetageneration());
    System.out.println("Name: " + blob.getName());
    System.out.println("Size: " + blob.getSize());
    System.out.println("StorageClass: " + blob.getStorageClass());
    System.out.println("TimeCreated: " + new Date(blob.getCreateTime()));
    System.out.println("Last Metadata Update: " + new Date(blob.getUpdateTime()));
    System.out.println("Object Retention Policy: " + blob.getRetention());
    Boolean temporaryHoldIsEnabled = (blob.getTemporaryHold() != null && blob.getTemporaryHold());
    System.out.println("temporaryHold: " + (temporaryHoldIsEnabled ? "enabled" : "disabled"));
    Boolean eventBasedHoldIsEnabled =
        (blob.getEventBasedHold() != null && blob.getEventBasedHold());
    System.out.println("eventBasedHold: " + (eventBasedHoldIsEnabled ? "enabled" : "disabled"));
    if (blob.getRetentionExpirationTime() != null) {
      System.out.println("retentionExpirationTime: " + new Date(blob.getRetentionExpirationTime()));
    }
    if (blob.getMetadata() != null) {
      System.out.println("\n\n\nUser metadata:");
      for (Map.Entry<String, String> userMetadata : blob.getMetadata().entrySet()) {
        System.out.println(userMetadata.getKey() + "=" + userMetadata.getValue());
      }
    }
  }
}

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

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

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

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

async function getMetadata() {
  // Gets the metadata for the file
  const [metadata] = await storage
    .bucket(bucketName)
    .file(fileName)
    .getMetadata();

  console.log(`Bucket: ${metadata.bucket}`);
  console.log(`CacheControl: ${metadata.cacheControl}`);
  console.log(`ComponentCount: ${metadata.componentCount}`);
  console.log(`ContentDisposition: ${metadata.contentDisposition}`);
  console.log(`ContentEncoding: ${metadata.contentEncoding}`);
  console.log(`ContentLanguage: ${metadata.contentLanguage}`);
  console.log(`ContentType: ${metadata.contentType}`);
  console.log(`CustomTime: ${metadata.customTime}`);
  console.log(`Crc32c: ${metadata.crc32c}`);
  console.log(`ETag: ${metadata.etag}`);
  console.log(`Generation: ${metadata.generation}`);
  console.log(`Id: ${metadata.id}`);
  console.log(`KmsKeyName: ${metadata.kmsKeyName}`);
  console.log(`Md5Hash: ${metadata.md5Hash}`);
  console.log(`MediaLink: ${metadata.mediaLink}`);
  console.log(`Metageneration: ${metadata.metageneration}`);
  console.log(`Name: ${metadata.name}`);
  console.log(`Size: ${metadata.size}`);
  console.log(`StorageClass: ${metadata.storageClass}`);
  console.log(`TimeCreated: ${new Date(metadata.timeCreated)}`);
  console.log(`Last Metadata Update: ${new Date(metadata.updated)}`);
  console.log(`TurboReplication: ${metadata.rpo}`);
  console.log(
    `temporaryHold: ${metadata.temporaryHold ? 'enabled' : 'disabled'}`
  );
  console.log(
    `eventBasedHold: ${metadata.eventBasedHold ? 'enabled' : 'disabled'}`
  );
  if (metadata.retentionExpirationTime) {
    console.log(
      `retentionExpirationTime: ${new Date(metadata.retentionExpirationTime)}`
    );
  }
  if (metadata.metadata) {
    console.log('\n\n\nUser metadata:');
    for (const key in metadata.metadata) {
      console.log(`${key}=${metadata.metadata[key]}`);
    }
  }
}

getMetadata().catch(console.error);

PHP

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

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

如需查看对象的保留配置，请按照显示对象的元数据的说明操作，并在响应中查找保留字段。

use Google\Cloud\Storage\StorageClient;

/**
 * List object metadata.
 *
 * @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')
 */
function object_metadata(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $info = $object->info();
    if (isset($info['name'])) {
        printf('Blob: %s' . PHP_EOL, $info['name']);
    }
    if (isset($info['bucket'])) {
        printf('Bucket: %s' . PHP_EOL, $info['bucket']);
    }
    if (isset($info['storageClass'])) {
        printf('Storage class: %s' . PHP_EOL, $info['storageClass']);
    }
    if (isset($info['id'])) {
        printf('ID: %s' . PHP_EOL, $info['id']);
    }
    if (isset($info['size'])) {
        printf('Size: %s' . PHP_EOL, $info['size']);
    }
    if (isset($info['updated'])) {
        printf('Updated: %s' . PHP_EOL, $info['updated']);
    }
    if (isset($info['generation'])) {
        printf('Generation: %s' . PHP_EOL, $info['generation']);
    }
    if (isset($info['metageneration'])) {
        printf('Metageneration: %s' . PHP_EOL, $info['metageneration']);
    }
    if (isset($info['etag'])) {
        printf('Etag: %s' . PHP_EOL, $info['etag']);
    }
    if (isset($info['crc32c'])) {
        printf('Crc32c: %s' . PHP_EOL, $info['crc32c']);
    }
    if (isset($info['md5Hash'])) {
        printf('MD5 Hash: %s' . PHP_EOL, $info['md5Hash']);
    }
    if (isset($info['contentType'])) {
        printf('Content-type: %s' . PHP_EOL, $info['contentType']);
    }
    if (isset($info['temporaryHold'])) {
        printf('Temporary hold: %s' . PHP_EOL, ($info['temporaryHold'] ? 'enabled' : 'disabled'));
    }
    if (isset($info['eventBasedHold'])) {
        printf('Event-based hold: %s' . PHP_EOL, ($info['eventBasedHold'] ? 'enabled' : 'disabled'));
    }
    if (isset($info['retentionExpirationTime'])) {
        printf('Retention Expiration Time: %s' . PHP_EOL, $info['retentionExpirationTime']);
    }
    if (isset($info['retention'])) {
        printf('Retention mode: %s' . PHP_EOL, $info['retention']['mode']);
        printf('Retain until time is: %s' . PHP_EOL, $info['retention']['retainUntilTime']);
    }
    if (isset($info['customTime'])) {
        printf('Custom Time: %s' . PHP_EOL, $info['customTime']);
    }
    if (isset($info['metadata'])) {
        printf('Metadata: %s' . PHP_EOL, print_r($info['metadata'], true));
    }
}

Python

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

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

如需查看对象的保留配置，请按照显示对象的元数据的说明操作，并在响应中查找保留字段。

from google.cloud import storage


def blob_metadata(bucket_name, blob_name):
    """Prints out a blob's metadata."""
    # bucket_name = 'your-bucket-name'
    # blob_name = 'your-object-name'

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Retrieve a blob, and its metadata, from Google Cloud Storage.
    # Note that `get_blob` differs from `Bucket.blob`, which does not
    # make an HTTP request.
    blob = bucket.get_blob(blob_name)

    print(f"Blob: {blob.name}")
    print(f"Blob finalization: {blob.finalized_time}")
    print(f"Bucket: {blob.bucket.name}")
    print(f"Storage class: {blob.storage_class}")
    print(f"ID: {blob.id}")
    print(f"Size: {blob.size} bytes")
    print(f"Updated: {blob.updated}")
    print(f"Generation: {blob.generation}")
    print(f"Metageneration: {blob.metageneration}")
    print(f"Etag: {blob.etag}")
    print(f"Owner: {blob.owner}")
    print(f"Component count: {blob.component_count}")
    print(f"Crc32c: {blob.crc32c}")
    print(f"md5_hash: {blob.md5_hash}")
    print(f"Cache-control: {blob.cache_control}")
    print(f"Content-type: {blob.content_type}")
    print(f"Content-disposition: {blob.content_disposition}")
    print(f"Content-encoding: {blob.content_encoding}")
    print(f"Content-language: {blob.content_language}")
    print(f"Metadata: {blob.metadata}")
    print(f"Medialink: {blob.media_link}")
    print(f"Custom Time: {blob.custom_time}")
    print("Temporary hold: ", "enabled" if blob.temporary_hold else "disabled")
    print(
        "Event based hold: ",
        "enabled" if blob.event_based_hold else "disabled",
    )
    print(f"Retention mode: {blob.retention.mode}")
    print(f"Retention retain until time: {blob.retention.retain_until_time}")
    if blob.retention_expiration_time:
        print(
            f"retentionExpirationTime: {blob.retention_expiration_time}"
        )

REST API

JSON API

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

使用 cURL 通过包含 retention 字段的 GET Object 请求调用 JSON API：
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/OBJECT_NAME?fields=retention"
```
其中：
- BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
- OBJECT_NAME 是相关对象的名称，例如 kitten.png。

XML API

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

使用 cURL 通过范围限定为 ?retention 的 GET Object 请求调用 XML API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"
```
其中：
- BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
- OBJECT_NAME 是相关对象的名称，例如 kitten.png。

后续步骤

详细了解保留配置。
了解保护 Cloud Storage 数据的其他功能。
了解对象生命周期管理，它可以在文件达到保留期限后自动删除文件。

启用和使用对象保留配置 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

所需的角色

所需权限

为存储桶启用对象保留

控制台

命令行

客户端库

C++

C#

Java

Node.js

PHP

Python

REST API

JSON API

XML API

查看存储桶的对象保留状态

控制台

命令行

客户端库

C++

C#

Java

Node.js

PHP

Python

REST API

JSON API

XML API

设置对象的保留配置

控制台

命令行

客户端库

C++

C#

Java

Node.js

PHP

Python

REST API

JSON API

XML API

查看对象的保留配置

控制台

命令行

客户端库

C++

C#

Java

Node.js

PHP

Python

REST API

JSON API

XML API

后续步骤

启用和使用对象保留配置