存储空间(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),如下图所示。
通过 PUT 操作第一次上传同名 Object (key=example.jpg)时,原始 Object 版本(ID=111111)作为历史版本,生成的新版本(ID=222222)将作为当前版本保存在存储空间中。当再次上传同名 Object 时,原始 Object 版本(包括 ID=111111 以及 ID=222222)将作为历史版本,而生成的新版本(ID=333333)则作为当前版本保存在 Bucket 中,如下图所示。

列举文件

在开启了版本控制的 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 的当前版本,且当前版本不能为删除标记。

下载文件

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

通过 GET 请求下载 Object 时,如果没有指定 Object 的版本 ID,默认情况下返回 Object 的当前版本。如下图所示返回 Object 的当前版本(ID=333333)。
在当前版本为删除标记(Delete Marker)时执行 GET 操作则返回 404 Not Found。
如果要下载指定的 Object 版本,则通过 GET 请求下载 Object 时需要指定其版本 ID ,如下图所示获取的 Object 指定版本为(ID=222222)。

删除文件

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

说明 开启版本控制后,删除 Object 时默认不会删除 Object 的当前版本以及历史版本。
在开启版本控制的 Bucket 中通过 DELETE 操作删除 Object 时,
  • 如果未指定 Object 的版本 ID ,则 OSS 会插入一个删除标记作为当前版本,该删除标记也会有相应的唯一版本 ID,但没有相关数据和 ACL 等,如下图所示(当前版本为删除标记,且版本 ID=444444 )。
  • 如果指定 Object 的版本 ID,即使用 DELETE versionId 的方式,则永久删除该指定版本的 Object ,如下图所示(即删除版本 ID=333333 的 Object )。

恢复文件

开启版本控制后,存储空间(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 的当前版本来恢复 Object 的早期版本

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

说明
  • 建议您使用 CopyObject 的方式来恢复 Object 的早期版本。
  • 您可以通过配置 Lifecycle 规则来删除 Object 的历史版本。