文档

文件多版本

更新时间:

本文档描述网盘与相册服务的文件多版本功能,您可以通过PDS提供的默认客户端使用多版本功能,也可以参考该文档调用API实现文件多版本的管理。

文件多版本属于增值功能,默认未开启,使用前请联系我们

基本概念

个人云盘或团队云盘中,文件和文件夹是树形结构:

多版本图片

  • 文件夹没有版本,文件有n个版本(n>=1)。

  • 新建文件,或编辑已有文件,产生文件版本。新建文件时,文件只有一个版本。编辑或覆盖一个已有文件,会产生新版本。如果未开启多版本,文件只保留最新版本;如果开启了多版本,产生新版本时,会将当前版本保留为历史版本,并根据配置的规则控制历史版本的数量。

  • 文件的历史版本,占用云盘空间容量。

功能点

1、编辑或覆盖文件会产生历史版本,支持列举、查看、恢复、删除历史版本,支持为历史版本设置标记信息。

2、支持配置版本保存期限(1-999天),或者设置不超期,支持进行周期内版本自动合并以避免产生过多历史版本。

3、支持配置版本保存个数(1-999个),并支持将最多50个版本设置为永久保留,永久保留的版本不会因超期或超过数量限制而被删除。

配置管理

开通文件多版本功能后,管理员可以在PDS提供的默认Web客户端,管理控制台-->企业设置-->历史版本界面,管理多版本/历史版本的配置。

API 调用流程及示例

(1)生成新版本

上传文件后,文件只有一个版本。覆盖上传文件后,文件会产生新版本。覆盖上传的逻辑,可参考文件上传最佳实践中的相关描述。覆盖文件的基本逻辑是:在CreateFile - 创建文件或文件夹接口中,设置 file_id 为要覆盖的文件ID,其它流程和普通上传一致。

(2)列举历史版本

调用ListRevision - 列举版本接口,获取单个文件的版本列表,支持分页。返回的版本列表,以产生的时间倒序排序,越近产生的版本,排序越靠前。

请求示例:

{
	"drive_id":"1",
	"file_id": "xxxxxx"
}

响应示例:

{
	"items": [{
		"domain_id": "xxxxxx",
		"drive_id": "1",
		"file_id": "xxxxxx",
		"revision_id": "xxxxxx",
		"revision_name": "history_version.xlsx",
		"file_extension": "xlsx",
		"size": 8493,
		"revision_version": 2,
		"keep_forever": false,
		"revision_description": "",
		"revision_create_reason": "overwrite",
		"content_hash_name": "sha1",
		"content_hash": "xxxxxx",
		"crc64_hash": "xxxxxx",
		"created_at": "2022-09-05T04:00:09.017Z",
		"updated_at": "2022-09-05T04:00:09.017Z",
		"creator_type": "User",
		"creator_id": "xxxxxx",
		"is_latest_version": true
	}],
	"next_marker": ""
}

注意:

  • 请求参数drive_id,是个人空间或团队空间的ID。

  • 请求参数file_id,是文件ID,不能是文件夹ID。

  • 分页获取时,请求响应中的参数next_marker是下一页起始资源标识符,可设置为下一次请求的marker参数。当一次请求的响应参数next_marker为空时,表示已经获取到最后一页。

  • 响应参数revision_version,表示版本编号,编号越小,产生的时间越早。

  • 响应参数revision_create_reason,表示版本生成的方式,有效值包括:

    • "":新建

    • "overwrite":覆盖更新

    • "restore_rev":历史版本还原

  • 响应参数is_latest_version,标识文件是否为最新版本。

  • 响应参数revision_name,最新版本的名字,和文件保持一致;历史版本的名字,在历史版本生成时固定。

(3)获取版本信息

调用GetRevision - 获取版本信息信息接口,可以获取单个版本的详情。与列举历史版本接口相比,获取版本信息接口的响应信息增加了下载地址。

请求示例:

{
	"drive_id":"1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx"
}

返回示例:

{
	"domain_id": "xxxxxx",
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx",
	"revision_name": "history_version.xlsx",
	"file_extension": "xlsx",
	"size": 8493,
	"revision_version": 2,
	"keep_forever": false,
	"revision_description": "",
	"revision_create_reason": "overwrite",
	"content_hash_name": "sha1",
	"content_hash": "xxxxxx",
	"crc64_hash": "xxxxxx",
	"created_at": "2022-09-05T04:00:09.017Z",
	"updated_at": "2022-09-05T04:00:09.017Z",
	"creator_type": "User",
	"creator_id": "xxxxxx",
	"is_latest_version": true,
	"download_url": "xxxxxx"
}

(4)更新版本信息

调用UpdateRevision - 更新版本信息接口,可以设置版本的属性。包括:

<1> 设置永久保留某个版本

请求示例:

{
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx",
	"keep_forever": true
}

<2> 取消永久保留某个版本

请求示例:

{
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx",
	"keep_forever": false
}

注意:

  • 支持将最多50个版本设置为永久保留,永久保留的版本不会因超期或超过数量限制而被删除。

  • 永久保留的版本,可以通过删除历史版本删除。

  • 永久保留的版本,在彻底删除文件时会被删除。

<3> 设置版本的描述信息

请求示例:

{
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx",
	"revision_description": "this is a revision"
}

(5)还原历史版本

调用RestoreRevision - 还原历史版本接口,可以将一个历史版本还原为文件的最新版本。

请求示例:

{
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx"
}

注意:

  • 该接口不支持还原文件的最新版本。

  • 还原版本时,以一个历史版本来生成一个新版本,历史版本状态不变,新版本的创建者为还原历史版本的操作者。如果需要清理历史版本以释放其占用的空间,需要主动调用DeleteRevision - 删除历史版本接口。

(6)删除历史版本

调用DeleteRevision - 删除历史版本接口,可以删除一个历史版本,释放其占用的空间。

请求示例:

{
	"drive_id": "1",
	"file_id": "xxxxxx",
	"revision_id": "xxxxxx"
}

注意:

  • 该接口不支持删除文件的最新版本。

常见问题

(1)版本合并的作用

开启时,对文件在10分钟周期内的多次保存结果(如在线编辑保存、同步盘上传)将合并保留最后一个历史版本,以避免频繁保存造成版本过多。10分钟的合并周期,是指10:00-10:1010:10-10:20这样的时间段。

关闭时,每次保存结果均生成一个历史版本(包含自动保存和手动保存)。

(2)文件第一个版本是否会一直保留

文件第一个版本,是在创建文件时产生的,会受版本保存期限、保存个数的限制。如果文件第一个版本是历史版本,超过了设置的保存期限,会被清理。如果文件的总版本数超过设置的保存个数,会从最早的版本开始清理,也可能删除第一个版本。如果要保留,请将特定版本通过界面或API设置为永久保留。

文件的最新版本,不会被版本清理机制删除。

  • 本页导读 (0)