How to use the revert command to restore versions of deleted objects - 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 an 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 Versioning.
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 deleted 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. NOW~ relative time: When you use relative time indexing, you can go back a specific time interval from the current local time. The format is `NOW~` followed by a time unit suffix. The supported unit suffixes are: ms for milliseconds, s for seconds, m for minutes, h for hours, d for days, w for weeks, M for months, and y for years. Example: `NOW~1d` means to restore to the version from one day before the current local time. NOW~ absolute time: For cases that require a specific date and time, you can use an absolute time index. The format is `NOW~` followed by a time string that conforms to the ISO 8601 standard (`YYYY-MM-DDTHH:mm:ss`), which will restore the most recent version before the specified local time. Example: `NOW~2024-04-12T14:00:00` indicates that the object version is restored to the most recent previous version whose last modified time is not later than 14:00:00, April 12, 2024.
-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 the 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 paths or object names.
--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 paths or object names.
--filter-from	stringArray	Specifies that the filter rule for the paths or object names 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 paths or object names.
--include-from	stringArray	Specifies that the inclusion rule is read from the rules file.
--max-age	Duration	Restores only objects whose last modified time is within the specified duration. The default unit is seconds. You can also use a suffix, such as 1h for one hour. Note `--min-age 1h` indicates that only objects modified within the last hour are restored.
--min-mtime	Time	Restores only objects whose last modified time is after the specified time. Example: 2006-01-02T15:04:05. Note `--min-mtime "2006-01-02T15:04:05"` indicates that only files modified after 2006-01-02 15:04:05 are restored.
--page-size	int	The maximum number of objects to list per API request during batch operations. Default value: 1000. Value range: 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. Valid value: 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 version of a single object

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 deleted versions of multiple objects

Restore all 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 all 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
```
Restore all objects except objects in the JPG format in the examplebucket bucket to the most recent previous version:
```
ossutil revert oss://examplebucket -r --exclude "*.jpg" HEAD~0
```
Restore all objects whose suffixes are .txt in the dir1 and dir2 directories of the examplebucket bucket to the most recent previous version:
```
ossutil revert oss://examplebucket -r --include "/dir1/*.txt" --include "/dir2/*.txt" HEAD~0
```
Read the inclusion rule from the include_rules.txt file and restore the objects that meet the rules in the dir directory of the examplebucket bucket to the fourth most recent previous version:
The content of the rule file include_rules.txt is as follows:
```
*.log
*.csv
```
Sample command:
```
ossutil revert oss://examplebucket/dir -r HEAD~4 --include-from include_rules.txt
```