文件多版本

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

基本概念

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

• 文件夹没有版本，文件有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:10、10:10-10:20这样的时间段。

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

（2）文件第一个版本是否会一直保留

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

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