How to run the revert command to restore a deleted object version - Object Storage Service

You can run the revert command to restore a deleted object version in a versioning-enabled bucket to the most recent previous version.

Usage notes

To restore a deleted object version, you must have the oss:GetObject, oss:PutObject, oss:ListObjectVersions, and oss:DeleteObject permissions. For more information, see Attach a custom policy to a RAM user.

For more information about versioning, see Overview.
For more information about delete markers, see Delete marker.

Command syntax

ossutil revert oss://bucket[/prefix] version-directive [flags]

Parameter	Type	Description
version-directive	string	The version of the object that you want to restore. Valid values: The version ID. Example: CAEQIBiBgICAr6yv9hgiIDZiNmUzNjM5Njg0ZDRhOWQ4Yj. The version index. Format: HEAD~n. The object version is restored to the n-1 valid version, excluding the delete marker. If the version index is set to HEAD~0, the object version is restored to the most recent previous version. If the latest version is a delete marker, the object version is restored to the most recent previous version by deleting the delete marker. If the version index is set to HEAD~n (n > 0), the object version is restored to the most recent previous version by copying the object version. The time index. Format: NOW~Relative time or NOW~Absolute time. The object version is restored to the most recent previous version whose last modified time is not later than the specified time, excluding the delete marker. If the time index is set to NOW~Relative time, such as NOW~1d, the object version is restored to the most recent previous version in the previous day. Unit: ms, s, m, h, d, w, m, and y. If the time index is set to NOW~Absolute time, such as NOW~2024-04-12T14:00:00, the object version is restored to the most recent previous version whose last modified time is not later than 2024-04-12T14:00:00.
-d, --dirs	/	Specifies that the objects and subdirectories in the current directory are returned.
--encoding-type	string	The encoding method used to encode the object name. Valid value: url.
--end-with	string	Specifies that objects whose names are alphabetically before or the same as the value of the --end-with parameter are returned.
--exclude	stringArray	The exclusion rule for the path or object name.
--exclude-from	stringArray	Specifies that the exclusion rule is read from the rules file.
--files-from	stringArray	Specifies that the source object names are read from the rules file, and empty lines or comment lines are ignored.
--files-from-raw	stringArray	Specifies that the source object names are read from the rules file.
--filter	stringArray	The filter rule for the path or object name.
--filter-from	stringArray	Specifies that the filter rule for the path or object name is read from the rules file.
-f, --force	/	Specifies that the command is forcibly run without a prompt for confirmation.
--ignore-version-not-exist	/	Specifies that errors indicating non-exist versions are ignored in batch operations.
--include	stringArray	The inclusion rule for the path or object name.
--include-from	stringArray	Specifies that the inclusion rule is read from the rules file.
--max-age	Duration	Specifies that the objects whose last modified time is earlier than the value of the --max-age parameter are not restored. The default unit is seconds. The unit can be milliseconds, seconds, minutes, hours, days, weeks, months, or years. By default, this parameter is left empty.
--min-mtime	Time	Specifies that the objects whose last modified time is earlier than the value of the --min-mtime parameter are not restored. The value is in UTC. By default, this parameter is left empty.
--page-size	int	The maximum number of objects that can be returned. Default value: 1000. Valid values: 1 to 1000.
-r, --recursive	/	Specifies that the command is recursively run on objects. If this parameter is specified, the revert command takes effect on all objects that meet the conditions in the bucket. Otherwise, the revert command takes effect on only the objects in the specified path.
--request-payer	string	The payer of the request. If pay-by-requester is enabled for the bucket, set this parameter to requester.
--start-after	string	Specifies that objects whose names are alphabetically after the value of the --start-after parameter are returned.

Note

For more information, see Command-line options.

Note: You cannot run the revert command to delete object versions to restore an object to a specific object version. To restore an object to a specific version by deleting versions, run the rm command. For example, you can run the following command to delete the three most recent previous versions of an object named key123.

ossutil rm oss://bucket/key123 --end-with key123 --limited-num 3 -rf --all-versions

Examples

Restore the deleted example.txt object in the examplebucket bucket to a version whose version ID is 123:
```
ossutil revert oss://examplebucket/example.txt 123
```
Restore the deleted example.txt object in the examplebucket bucket to the most recent previous version:
```
ossutil revert oss://examplebucket/example.txt HEAD~0
```
Restore the deleted example.txt object in the examplebucket bucket to the fourth most recent previous version:
```
ossutil revert oss://examplebucket/example.txt HEAD~4
```
Restore the deleted example.txt object in the examplebucket bucket to the most recent previous version in the previous day:
```
ossutil revert oss://examplebucket/example.txt NOW~1d
```
Restore the deleted example.txt object in the examplebucket bucket to the most recent previous version whose last modified time is not later than 2024-04-12T14:00:00:
```
ossutil revert oss://examplebucket/example.txt NOW~2024-04-12T14:00:00
```
Restore the objects in the dir directory of the examplebucket bucket to the fourth most recent previous version:
```
ossutil revert oss://examplebucket/dir -r HEAD~4
```
Restore the objects in the dir directory of the examplebucket bucket to the fourth most recent previous version and ignore errors indicating that versions do not exist:
```
ossutil revert oss://examplebucket/dir -r HEAD~4 --ignore-version-not-exist
```