Use ossutil V2.0 to restore multiple objects at a time-Object Storage Service(OSS)-阿里云帮助中心

Archive, Cold Archive, and Deep Cold Archive objects are frozen to minimize storage costs and cannot be directly accessed. To access these objects, use the restore command of ossutil V2.0 to restore them first.

Note

Archive objects support direct access if you enable real-time access of Archive objects. However, Cold Archive and Deep Cold Archive objects must be restored before they can be accessed.

Prerequisites

OSS is activated, and a bucket is created.
ossutil V2.0 is installed.
You are granted the oss:RestoreObject and oss:ListObjects permissions if you restore objects as a RAM user or by using temporary access credentials provided by Security Token Service (STS). However, if you restore objects by using an Alibaba Cloud account, you do not need to grant the permissions. An Alibaba Cloud account has the permissions required to restore objects by default. For more information, see Grant a custom policy.

Batch restoration

ossutil V2.0 supports the following methods to specify objects for batch restoration:

Specify the prefix in the names of the objects.
Specify a plain list or inventory of the objects.

Usage notes

When you restore a large number of objects, set the --days parameter to a higher value to ensure that all objects remain accessible when the restoration completes. To put restored objects back in the frozen state early, use the unrestore (Remove restored objects) command to delete the replicas created during restoration.
The -j parameter sets the number of concurrent tasks. If your CPU and memory permit, we recommend that you set -j to 128 for improved performance.
You can use object metadata fields to filter objects, such as skipping objects that are already restored or being restored.
When you restore multiple objects at a time, errors are recorded in the ossutil_output/ directory.

Command syntax

ossutil restore oss://bucket/object [flags]

Parameter	Type	Description
-r, --recursive	/	Enables recursive mode. When specified, the operation applies to all matching objects in the bucket. Otherwise, only objects in the specified path are processed.
-j, --job	/	The number of concurrent tasks for a multi-object operation. Valid values: 1 to 10000. Default value: 3.
--days	int	The duration for which the object remains in the restored state. Unit: days. Valid values: 1 to 365. Note If the batch operation involves objects in different storage classes and the `--days` value exceeds the maximum allowable duration for a storage class, the maximum limit for that class applies. For example, the maximum supported duration is 7 days for Archive objects and 365 days for Deep Cold Archive objects. Therefore, if the `--days` parameter is set to 100, the restored state duration will automatically adjust to 7 days for Archive objects while remaining fixed at 100 days for Deep Cold Archive objects.
--metadata-include	stringArray	Metadata filtering rules to include objects. Only objects that match the specified rules are included in the operation.
--metadata-exclude	stringArray	Metadata filtering rules to exclude objects. Objects that match the specified rules are excluded from the operation.
--list-format	string	The format of the list file. Valid values: `plain` and `inventory`.
--list-manifest-from	string	Required when `--list-format` is set to `inventory`. Configure this parameter to read descriptions from the file.

For a complete list of parameters supported by the command, see Parameters.

Examples

Restore all objects that have the same prefix in object names

The following command restores objects whose names start with prefix in a bucket named examplebucket:

ossutil restore -r -j 128 oss://examplebucket/prefix

Restore objects in a specific storage class

Note

Note the multi-condition filtering logic in ossutil V2.0:

Inclusion conditions are evaluated from left to right. If an object or directory matches a condition, it is immediately included.
Exclusion conditions are evaluated from left to right. If an object or directory matches a condition, it is immediately excluded.

Therefore, if you want to restore all Cold Archive objects that are not in the restored state by specifying inclusion and exclusion conditions, you must place --metadata-exclude "x-oss-restore=*" before --metadata-include "x-oss-storage-class=ColdArchive" in the command.

The following command restores all Cold Archive objects in the examplebucket bucket:

ossutil restore -r -j 128  oss://bucket --metadata-include "x-oss-storage-class=ColdArchive"

The following command restores all unrestored Cold Archive objects in the examplebucket bucket and keeps them in the restored state for 7 days:

ossutil restore -r -j 128 oss://bucket --days=7 --metadata-exclude "x-oss-restore=*" --metadata-include "x-oss-storage-class=ColdArchive"

Restore objects by using a local list file

You can use a local list file to specify objects to restore, with each object on a separate line in its standard OSS path format. Example:

oss://examplebucket/object1
oss://examplebucket/object2
oss://examplebucket/object3

The following command restores unrestored objects specified in object_list.txt and keeps them in the restored state for 7 days:

ossutil restore list://object_list.txt --days=7 --no-check-status

Note

When restoring objects from a local list file, you can add the --no-check-status parameter to skip object status checks before restoration for improved performance. This parameter is supported by ossutil V2.0.4 and later.

Restore objects by using a local inventory list file

Note

An inventory task generates two files: csv.gz and manifest.json. Both files are required to restore objects based on an inventory list.

The following command restores all Cold Archive objects from OSS inventory lists:

ossutil restore list://object_list.csv.gz --list-format inventory --list-manifest-from manifest.json --days=7 --no-check-status --metadata-include "x-oss-storage-class=ColdArchive"