What are historical versions of a file? - Drive and Photo Service

Background

Files and folders are stored in the tree structure in a personal space or an enterprise drive.

A folder has no historical versions. A file has n historical versions, where n is an integer greater than or equal to 1.
A file version is generated after you create or modify a file.
After you create a file, the file has only one version.
After you modify or overwrite an existing file, a new file version is generated.
If multi-version is disabled, only the latest version of a file is retained.
If multi-version is enabled, when a new version is created, the current version is kept as a historical version, and retention rules control how many historical versions are kept.
The historical versions of a file occupy the storage space of your drive.

With file versioning, you can list, query, restore, and delete historical versions, add tags to versions, and configure retention and merge policies.

Prerequisites

A PDS Developer Edition domain is created.
Only a super administrator or drive administrator can enable this feature.
BasicUI is enabled. See Enable BasicUI.

Enable historical versioning

Log on to BasicUI and go to the admin console. For information about how to log on to BasicUI, see Log on to BasicUI.
In the left-side navigation pane, choose Enterprise Settings > File Settings.
Turn on Historical Version.

Historical version configuration

Click Edit in the upper-right corner of the File Settings page to modify the historical version configuration.

Feature	Description
Merge file history versions	This option is enabled by default. When enabled, file versions generated within 10 minutes are merged, and only the latest historical version is retained. This prevents too many historical versions when files are saved frequently, such as during online editing or synchronization between an on-premises disk and a cloud drive. When disabled, a historical version is generated every time the file is saved, whether manually or automatically.
Set the upper limit of the number of versions	Set the value to an integer between 1 and 999. Except for historical versions that are permanently saved, other historical versions exceeding the upper limit are automatically deleted. Too many historical versions can make version management difficult and consume excessive storage space. Set a reasonable value.
Set the version storage period	Set the value to an integer between 1 and 999. Unit: days. Except for historical versions that are permanently saved, other historical versions exceeding the storage period are automatically deleted. Long-term historical versions can make version management difficult and consume excessive storage space. Set a reasonable value.

API operations and call examples

CreateFile

After you upload a file to PDS to create a file, the file has only one version. After you upload a file to PDS to overwrite an existing file, a new version of the file is generated.

For information about uploading a file to PDS to overwrite an existing file, see the "File upload in overwrite mode" section of the Upload a file topic. To overwrite an existing file, set the file_id parameter to the ID of the file to be overwritten when you call the CreateFile operation. The other configurations are the same as those for uploading a file to create a file.

ListRevision

Call the ListRevision operation to query historical versions of a file by page. Results are returned in reverse chronological order, from newest to oldest.

Sample request

{
	"drive_id":"testDriveId",
	"file_id": "testFileId"
}

Sample response

{
	"items": [{
		"domain_id": "testDomainId",
		"drive_id": "testDriveId",
		"file_id": "testFileId",
		"revision_id": "testRevisionId",
		"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": "testCreatorId",
		"is_latest_version": true
	}],
	"next_marker": ""
}

Parameter description

drive_id (request): the ID of the personal space or enterprise drive that contains the target file.
file_id (request): the ID of the file whose historical versions you want to query. Folder IDs are not supported.
next_marker (response): the pagination token for the next page. To query the next page, set the marker request parameter to this value. If next_marker is empty, the current page is the last page.
revision_version (response): the version number. A smaller value indicates an earlier version.
revision_create_reason (response): the reason the version was created. Valid values:
- Empty string: the file was created.
- overwrite: an existing file was overwritten.
- restore_rev: a historical version was restored.
is_latest_version (response): indicates whether the returned version is the latest file version.
revision_name (response): the version name. The latest version name is the same as the current file name. A historical version name is fixed when that version is created.

GetRevision

Call the GetRevision operation to query details of a historical version. Compared with ListRevision, GetRevision adds the download_url parameter in the response.

Sample request

{
	"drive_id":"testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

Sample response

{
	"domain_id": "testDomainId",
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"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": "testCreatorId",
	"is_latest_version": true,
	"download_url": "testDownloadUrl"
}

UpdateRevision

Call the UpdateRevision operation to configure file version properties.

Enable a file version to be permanently retained

Important

Permanently retain up to 50 historical versions of a file. Permanently retained versions are not deleted even if the retention period elapses or the maximum number of historical versions is exceeded.
To delete a permanently retained historical version, call the DeleteRevision operation.
The historical versions of a file that are permanently retained are deleted if the file is permanently deleted.

Sample request

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"keep_forever": true
}

Disable a file version from being permanently retained

Sample request

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"keep_forever": false
}

Specify the description of a file version

Sample request

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"revision_description": "this is a revision"
}

RestoreRevision

Important

You cannot call this operation to restore the latest version of a file.
When you restore a historical version of the file, a new version is generated based on the historical version. The status of the historical version remains unchanged. The creator of the new version is the operator who restores the historical version. To delete a historical version to release the storage space occupied by the historical version, you must call the DeleteRevision operation.

Call the RestoreRevision operation to restore a historical version as the latest version of a file.

Sample request

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

DeleteRevision

Important

You cannot call this operation to delete the latest version of a file.

Call the DeleteRevision operation to delete a historical version and release its storage space.

Sample request

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

FAQ

What are the benefits of version merge?

When version merge is enabled, file versions generated within a 10-minute cycle are merged, and only the latest historical version is retained. This prevents too many historical versions when files are saved frequently, such as during online editing or synchronization between an on-premises disk and a cloud drive. A 10-minute cycle means a fixed 10-minute window, for example, 10:00-10:10 or 10:10-10:20.
When version merge is disabled, a historical version is generated every time the file is saved, whether manually or automatically.

Can the first version of a file be permanently retained?

The first version of a file is generated when the file is created.
If the first version of the file is a historical version, the version is deleted after the specified retention period elapses.
If the total number of historical versions exceeds the configured limit, the earliest version is deleted. In this case, the first version may be deleted. Use the PDS console or call the UpdateRevision operation to permanently retain the first version.
The latest version of the file cannot be deleted.

How do I disable historical versioning?

Historical versioning cannot be disabled after it is enabled. To stop using it, set the upper limit of versions to 1. This has the same effect as not enabling versioning.