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

This topic describes the historical version feature of Drive and Photo Service (Developer Edition). You can use the historical version feature in the default BasicUI provided by PDS. You can also call API operations of PDS to manage the historical versions of a file by referring to this topic.

Basic concepts

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

A folder has no historical versions, and a file has n historical versions. The value of n is an integer that is equal to or greater than 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 the historical version feature is disabled, only the latest version of the file is retained.
If the historical version feature is enabled, the current file version is retained as a historical version of the file after a new file version is generated. The number of historical versions is controlled based on the configured rules.
The historical versions of a file occupy the storage space of your drive.

Feature description

You can enable the historical version feature of a file to back up multiple versions of a file. This way, you can save the file and its historical versions and easily restore the file even if the file is overwritten or incorrectly modified.
If you modify or overwrite a file, a new file version is generated. You can query all historical versions of the file, query the details of a historical version of the file, restore a historical version of the file, or delete a historical version of the file. You can also add tags to a historical version of the file.
You can configure a retention period for the historical versions of a file. The retention period can be 1 to 999 days. You can also permanently retain specific historical versions of the file and configure the historical versions of the file to be periodically merged to prevent the accumulation of historical versions.
You can retain 1 to 999 historical versions of a file and permanently retain up to 50 historical versions of the file. The historical versions of the file that are permanently retained are not deleted even if the retention period of the historical versions elapses or the maximum number of historical versions of the file is exceeded.

Prerequisites

A PDS Developer Edition domain is created.
Only a super administrator or drive administrator can enable this feature.
BasicUI is enabled. For more information, see Enable BasicUI.

Enable the historical version feature

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

You can 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 feature is enabled by default. If this feature is enabled, the multiple versions of a file that are generated within 10 minutes are merged and only the latest historical version of the file is retained. This prevents a large number of historical versions from being generated if the file is frequently saved after you perform operations on the file, such as modifying and saving the file online or synchronizing the file between an on-premises disk and a cloud drive. If this feature is disabled, a historical version of a file is generated every time when you manually save the file or the file is automatically saved.
Set the upper limit of the number of versions	You can 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 cause chaotic version management and occupy too much storage space. We recommend that you set a reasonable value.
Set the version storage period	You can 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 cause chaotic version management and occupy too much storage space. We recommend that you 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

You can call the ListRevision operation to query the historical versions of a file by page. The returned results are sorted in reverse chronological order. Based on the time when the historical versions of the file are generated, the historical versions of the file are sorted from the most recent to the least recent.

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

The drive_id request parameter specifies the ID of the individual drive or enterprise drive in which the file whose historical versions you want to query resides.
The file_id request parameter specifies the ID of the file whose historical versions you want to query. You cannot specify a folder ID for this parameter.
If the results are returned by page, the next_marker response parameter indicates the pagination token that is used in the next request to retrieve a new page of results. You must specify the token that is obtained from the previous request as the value of the marker parameter of the next request. If no value is returned for the next_marker response parameter, the results of the last page are returned.
The revision_version response parameter indicates the version number. A smaller number indicates an earlier version.
The revision_create_reason response parameter indicates the reason why a version is generated. Valid values:
- An empty string: A file is created.
- overwrite: An existing file is overwritten.
- restore_rev: A historical version is restored.
The is_latest_version response parameter indicates whether the file is of the latest version.
The revision_name response parameter indicates the name of the latest version of the file. The name of the latest version of the file is the same as the name of the file. The name of a historical version is fixed when the historical version is generated.

GetRevision

You can call the GetRevision operation to query the details of a historical version. Compared with the ListRevision operation, the download_url parameter is added to the response of the GetRevision operation.

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

You can call the UpdateRevision operation to configure the properties of a file version.

Enable a file version to be permanently retained

Important

You can permanently retain up to 50 historical versions of a file. The historical versions of the file that are permanently retained are not deleted even if the retention period of the historical versions elapses or the maximum number of historical versions of the file is exceeded.
You can delete the historical versions of a file that are permanently retained by calling 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.

You can call the RestoreRevision operation to restore a historical version of a file as the latest version of the 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.

You can call the DeleteRevision operation to delete a historical version to release the storage space that is occupied by the historical version.

Sample request

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

FAQ

What are the benefits of the version merge feature?

If the version merge feature is enabled, the multiple versions of a file that are generated within a 10-minute cycle are merged and only the latest historical version of the file is retained. This prevents a large number of historical versions from being generated if the file is frequently saved after you perform operations on the file, such as modifying and saving the file online or synchronizing the file between an on-premises disk and a cloud drive. A 10-minute cycle indicates a cycle of 10 minutes. For example, a 10-minute cycle starts at 10:00 and ends at 10:10 or starts at 10:10 and ends at 10:20.
If the version merge feature is disabled, a historical version of a file is generated every time when you manually save the file or the file is automatically saved.

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 of the file exceeds the specified number, the earliest version of the file is deleted. In this case, the first version of the file may be deleted. You can use the PDS console or call the UpdateRevision operation to permanently retain the first version of the file.
The latest version of the file cannot be deleted.

How do I disable the historical version feature?

The historical version feature cannot be disabled after it is enabled. If you want to stop this feature, you can set the upper limit of the number of versions to 1. This has the same effect as if the feature were not enabled.