启用和使用对象保留配置

Overview

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

所需的角色

如需获得为存储桶启用对象保留锁定功能以及为对象设置保留配置所需的权限，请让您的管理员为您授予存储桶或存储桶所属项目的 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 与存储桶搭配使用。如需了解如何授予项目的角色，请参阅管理对项目的访问权限。

为存储桶启用对象保留

仅支持在创建存储桶时启用对象保留；在存储桶上启用对象保留后，便无法停用该功能。请按照以下说明为存储桶启用对象保留：

控制台

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

命令行

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

REST API

JSON API

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

XML API

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

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

如需查看存储桶是否启用了对象保留，请执行以下操作：

控制台

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

   进入“存储桶”

2. 点击您要查看其状态的存储桶的名称。

3. 点击保护标签页。

4. 存储桶的对象保留状态显示在对象保留部分中。

命令行

使用带有 --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

REST API

JSON API

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

   或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

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

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

   或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

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

设置对象的保留配置

注意：将保留配置的模式设置为 Locked（在 XML API 中是 COMPLIANCE）是无法撤销的操作。在完成该操作之后：

• 您无法从对象中移除保留配置。
• 您无法缩短对象的保留时间。

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

控制台

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

   进入“存储桶”

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

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

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

4. 点击对象的名称。

   此时会打开对象详情页面，其中显示对象元数据。

5. 在保护部分中，点击与来自对象保留配置关联的修改图标 ()。

   系统会打开修改保留窗格。

6. 在对象保留配置部分中，点击已启用或已停用。

   1. 如果已启用保留配置，请在保留到特定时间部分中为配置选择日期和时间，然后在保留模式部分中点击解锁或锁定。

7. 点击确认。

注意：您还可以在将对象上传到存储桶时设置对象的保留配置。如果对象要上传到的存储桶启用了对象保留功能，则上传期间会显示一个面板，可让您指定对象的保留配置。

命令行

使用带有相应标志的 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。

注意：您还可以在将对象写入存储桶时设置对象的保留配置。如需了解详情，请参阅命令文档，例如 gcloud storage cp。

REST API

JSON API

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

   或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

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

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

   其中：

   • STATE 是 Locked 或 Unlocked。

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

3. 使用 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 参数。

注意：您还可以在将对象写入存储桶时设置对象的保留配置。如需了解详情，请参阅请求文档，例如 Objects: Insert。

XML API

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

   或者，您可以使用 OAuth 2.0 Playground 创建访问令牌，并将其包含在 Authorization 标头中。

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

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

   其中：

   • STATE 是 GOVERNANCE 或 COMPLIANCE。

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

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

注意：您还可以在将对象写入存储桶时设置对象的保留配置。如需了解详情，请参阅请求文档，例如 PUT Object。

查看对象的保留配置

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

控制台

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

   进入“存储桶”

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

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

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

4. 点击对象的名称。

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

命令行

使用带有 --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

REST API

JSON API

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

   或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

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

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

   或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

2. 使用 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 数据的其他功能。
• 了解对象生命周期管理，它可以在文件达到保留期限后自动删除文件。