存储空间（Bucket）开启版本控制后，OSS 会为 Bucket 中所有文件（Object）的每个版本指定唯一的 ID 值，且 Bucket 中现有 Object 的内容、权限保持不变。开启版本控制后，还能够防止意外覆盖或者删除 Object ，并允许查询、恢复 Object 的历史版本。

说明
  • 必须针对 Bucket 显式开启版本控制。
  • 开启版本控制的 Bucket 会维护一个当前版本 Object，以及零个或零个以上历史版本 Object。
  • 如果未开启版本控制，OSS 将 Object 的版本 ID 值设置为 null。

您可以在开启了版本控制的 Bucket 中进行上传文件、列举文件、下载文件、删除文件、恢复文件等操作。

上传文件

在开启了版本控制的存储空间（Bucket）中上传文件（Object）时，OSS 会为这些上传的 Object 自动添加唯一的版本 ID。

说明 PutObject、PostObject、CopyObject 、MultipartUpload 等操作都会为新生成的 Object 自动添加唯一的版本 ID。
通过 PUT 操作上传 Object （key=example.jpg）时，OSS 为该 Object 指定了唯一的版本号（ID=111111），如下图所示。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第1张
通过 PUT 操作第一次上传同名 Object （key=example.jpg）时，原始 Object 版本（ID=111111）作为历史版本，生成的新版本（ID=222222）将作为当前版本保存在存储空间中。当再次上传同名 Object 时，原始 Object 版本（包括 ID=111111 以及 ID=222222）将作为历史版本，而生成的新版本（ID=333333）则作为当前版本保存在 Bucket 中，如下图所示。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第2张

列举文件

在开启了版本控制的 Bucket 中，您可以使用GetBucketVersions(ListObjectVersions)接口返回 Object 的所有版本信息，包括删除标记（Delete Marker）。

说明
  • 与 GetBucketVersions(ListObjectVersions) 不同的是，GetBucket (ListObject ) 接口仅返回 Object 的当前版本，且当前版本不为删除标记。
  • 每个请求最多返回 1000 个版本。如果需要列举 Object 的更多版本，则需要发送一系列请求才能列举所有 Object 的版本。

    例如，如果 Bucket 中包含两个 Key （如 example.jpg 和 photo.jpg），且第一个 Key （example.jpg）有 900 个版本，第二个 Key （photo.jpg）有 500 个版本，则单个请求将先按照 Key 的字母序，再按照版本的新旧顺序依次列举 example.jpg 的所有 900 个版本，另加 photo.jpg 的 100 个版本。

如下图所示，在开启了版本控制的 Bucket 中，调用 GetBucketVersions 接口时，返回了 Bucket 中所有 Object 的所有版本，包含当前版本为删除标记的 Object ；调用 GetBucket 接口时，则仅返回 Object 的当前版本，且当前版本不能为删除标记。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第3张

下载文件

您可以在开启了版本控制的存储空间（Bucket）中下载当前版本或指定版本的文件（Object）。

通过 GET 请求下载 Object 时，如果没有指定 Object 的版本 ID，默认情况下返回 Object 的当前版本。如下图所示返回 Object 的当前版本（ID=333333）。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第4张
在当前版本为删除标记（Delete Marker）时执行 GET 操作则返回 404 Not Found。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第5张
如果要下载指定的 Object 版本，则通过 GET 请求下载 Object 时需要指定其版本 ID ，如下图所示获取的 Object 指定版本为（ID=222222）。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第6张

删除文件

开启版本控制后，您可以通过指定 Object 对象版本 ID 或者配置 Lifecycle 将 Object 永久删除。如果删除 Object 时未指定版本 ID，则 Bucket 中将插入一个删除标记（Delete Marker）作为当前版本。

说明 开启版本控制后，删除 Object 时默认不会删除 Object 的当前版本以及历史版本。
在开启版本控制的 Bucket 中通过 DELETE 操作删除 Object 时，
  • 如果未指定 Object 的版本 ID ，则 OSS 会插入一个删除标记作为当前版本，该删除标记也会有相应的唯一版本 ID，但没有相关数据和 ACL 等，如下图所示（当前版本为删除标记，且版本 ID=444444 ）。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第7张
  • 如果指定 Object 的版本 ID，即使用 DELETE versionId 的方式，则永久删除该指定版本的 Object ，如下图所示（即删除版本 ID=333333 的 Object ）。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第8张

恢复文件

开启版本控制后，存储空间（Bucket）中文件（Object）的所有版本都将得以保留。您可以通过恢复指定历史版本的方式，使得任意 Object 的早期版本成为当前版本。

您可以通过以下两种方式将 Object 恢复至早期版本：
  • 通过 CopyObject 来恢复 Object 的早期版本

    复制的 Object 将成为该 Object 的当前版本，且所有 Object 版本都将保留。

    如下图所示，将原 Object 的历史版本（ID=222222）复制到同一个 Bucket 中，OSS 将为该 Object 生成新的版本 ID（ID=444444），并将其置为该 Object 的当前版本。因此，该 Object 同时具有历史版本（ID=222222）以及当前版本（ID=444444）。开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第9张
  • 通过删除 Object 的当前版本来恢复 Object 的早期版本

    如下图所示，当您通过 DELETE versionId 的方式永久删除当前 Object 版本（ID=222222）后， 下一个历史版本（ID=111111）成为了该 Object 的当前版本。

    开启版本控制_版本控制_对象/文件（Object）_开发指南_对象存储 OSS 阿里云技术文档 第10张
说明
  • 建议您使用 CopyObject 的方式来恢复 Object 的早期版本。
  • 您可以通过配置 Lifecycle 规则来删除 Object 的历史版本。