Run the restore command to restore Archive, Cold Archive, and Deep Cold Archive objects - Object Storage Service

You can access Archive objects if you enable real-time access of Archive objects or after you restore them. Real-time access is not supported for Cold Archive and Deep Cold Archive objects. You can access Cold Archive and Deep Cold Archive objects only after you restore them. In most cases, the restoration of an Archive object requires several minutes to complete, the restoration of a Cold Archive object requires several hours to complete, and the restoration of a Deep Cold Archive object requires 12 to 48 hours to complete. The given amounts of restoration time are for references. The restoration time may vary based on actual scenarios. This topic describes how to run the restore command to restore objects.

Usage notes

To restore a single object, you must have the oss:RestoreObject permission. To restore objects by directory, you must have the oss:RestoreObject and oss:ListObjects permissions. For more information, see Attach a custom policy to a RAM user.
For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.
For more information about the restoration process and billing rules, see Restore objects.
The restore command is supported by ossutil 1.7.11 and later.

Command syntax

ossutil restore oss://bucketname[/prefix][local_xml_file]
[--encoding-type <value>]
[--payer <value>]
[--version-id <value>]
[-r, --recursive]
[-f, --force] 
[--object-file, <value>]
[--snapshot-path, <value>]
[--disable-ignore-error]
[--retry-times <value>]
[-j, --job <value>]

The following table describes the parameters and options in the command syntax.

Parameter/Option	Description
bucketname	The name of the bucket in which the object you want to restore is stored.
prefix	The prefix in the names of the resources in the bucket, such as directories and objects.
local_xml_file	The local XML file that stores parameters for restoring Cold Archive objects.
--encoding-type	The method used to encode the value of the prefix parameter. Valid value: url. If you do not specify this option, the value of the prefix parameter is not encoded.
--payer	The payer of the request. If you want the requester who accesses the resources in the specified path to pay the fees that are generated by the operation, such as traffic and request fees, set this parameter to requester.
--version-id	The ID of the version of the object that you want to delete. This parameter applies only to a versioning-enabled or versioning-suspended bucket.
-r, --recursive	If you specify this option, ossutil restores all objects whose names contain the specified prefix in the bucket. If you do not specify this option, ossutil restores only the specified object.
-f, --force	Specifies that the command is forcibly run without a prompt for confirmation.
--object-file	The file that contains the names of Archive, Cold Archive, or Deep Cold Archive objects that you want to restore at a time. To use this option, perform the following steps: Specify a local TXT or XML file. Then, enter the names of all objects that you want to restore in the file, with each object name on a separate line. Set --object-file to the name of the local TXT or XML file and then run the command. ossutil reads all object names in the local file and restores the objects. Note If a restoration error is returned for one of the objects, ossutil records the error information about the object in the report file and continues to restore the other objects. Information about restored objects is not recorded in the report file.
--snapshot-path	If you specify this option, ossutil generates snapshots only for the objects that are involved in this operation. If snapshots have already been generated for the objects that are involved in this operation, no snapshots are generated for the objects in this operation. Note This option must be used together with -r, --recursive or --object-file.
--disable-ignore-error	Specifies that errors are not ignored for batch restoration.
--retry-times	The number of retries after the command fails to run. Default value: 10. Valid values: 1 to 500.
-j, --job	The number of concurrent tasks that are performed across multiple objects. Valid values: 1 to 10000. Default value: 3.

Restore Archive objects

OSS takes 1 minute to restore an Archive object. An object cannot be read while the object is being restored.

By default, a restored object remains in the restored state for one day. If you run the restore command for an object that is already in the restored state, the restored state is extended by one day. You can maintain a restored object in the restored state for up to seven days. After the period of the restored state ends, the object returns to the frozen state.

Note

You can run the cp command to change the storage class of an object. For more information, see Change the storage class of an object.

When you restore an Archive object, you can optionally create a config.xml file and specify the number of days for which you want the object to remain in the restored state in the file. The following sample code provides an example:

<RestoreRequest>
    <Days>3</Days>
</RestoreRequest>

Restore a single Archive object
- The following sample code provides an example on how to restore an Archive object named exampleobject.txt in the examplebucket bucket and retain the object in the restored state for three days:
```
ossutil restore oss://examplebucket/exampleobject.txt config.xml
```
- The following sample code provides an example on how to restore the specified version of an Archive object named exampleobject.txt in the examplebucket bucket:
```
ossutil restore oss://examplebucket/exampleobject.txt --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3**** config.xml
```
  For more information about how to list all versions of an object, see Is.
Restore multiple Archive objects at a time
- Example 1: Restore multiple Archive objects in different directories
  Assume that you want to restore the following Archive objects in different directories within the examplebucket bucket: exampleobject1.jpg in the root directory, exampleobject2.png in the dir1/ directory, and exampleobject3.txt in the dir2/ directory. You must perform the following steps to restore the objects:
  1. Write the names of the Archive objects that you want to restore to the localfile.txt file.
```
exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt
```
  2. In the config.xml file, specify that the objects remain in the restored state for three days.
```
<RestoreRequest>
    <Days>3</Days>
</RestoreRequest>
```
  3. Restore the Archive objects.
    The following command provides an example on how to restore multiple Archive objects in examplebucket by using the --object-file option:
```
ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml
```
- Example 2: Restore multiple Archive objects in the same directory
  - Method 1
    The steps to restore multiple Archive objects in the same directory within a bucket are similar to the steps described in Example 1: Restore multiple Archive objects in different directories.
  - Method 2
    The following command provides an example on how to restore all Archive objects in the dest directory in examplebucket by using the -r option:
```
ossutil restore oss://examplebucket/dest -r config.xml
```
Sample output
If the preceding command is successful, a line similar to the following one is included in the command output to indicate the restoration time consumed:
```
0.106852(s) elapsed
```

Restore Cold Archive objects

Important

The amount of time required to restore a Cold Archive object varies with the object size.

Before you restore one or more Cold Archive objects, you must create the XML file config.xml locally and configure the following parameters in the file:

<RestoreRequest>
    <Days>3</Days>
    <JobParameters>
        <Tier>Bulk</Tier>
    </JobParameters>
</RestoreRequest>

The following table describes the parameters.

Parameter

Description

Days

The duration for which you want to keep the restored Cold Archive object in the restored state. Unit: days.

Valid values: 1 to 365.

Tier

The restoration priority of the Cold Archive object.

Valid values:

Expedited: The object is restored within 1 hour.
Standard: The object is restored in 2 to 5 hours.
Bulk: The object is restored in 5 to 12 hours.

Restore a single Cold Archive object
The following command provides an example on how to restore the exampleobject.jpg object in the examplebucket bucket within 1 hour and keep the object in the restored state for three days based on the configurations specified in the config.xml file:
```
ossutil restore oss://examplebucket/exampleobject.jpg config.xml
```
Restore multiple Cold Archive objects at a time
- Example 1: Restore multiple Cold Archive objects in different directories
  Assume that you want to restore the following Cold Archive objects in different directories of the examplebucket bucket: exampleobject1.jpg in the root directory, exampleobject2.png in the dir1/ directory, and exampleobject3.txt in the dir2/ directory. Perform the following steps to restore the objects:
  1. Write the names of the Cold Archive objects that you want to restore to the localfile.txt file.
```
exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt
```
  2. Restore the objects.
    The following command provides an example on how to restore multiple Cold Archive objects in the examplebucket bucket within 1 hour by using the --object-file option and keep the object in the restored state for three days based on the configurations specified in the config.xml file:
```
ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml
```
- Example 2: Restore multiple Cold Archive objects in the same directory
  - Method 1
    The steps to restore multiple Cold Archive objects in the same directory within a bucket are similar to the steps described in Example 1: Restore multiple Cold Archive objects in different directories.
  - Method 2
    The following command provides an example on how to restore all Cold Archive objects in the dest directory within the examplebucket bucket by using the -r option:
```
ossutil restore oss://examplebucket/dest -r config.xml
```
Sample output
If the preceding command is successful, a line similar to the following one is included in the command output to indicate the restoration time consumed:
```
0.106852(s) elapsed
```

Restore Deep Cold Archive objects

Important

The amount of time required to restore a Deep Cold Archive object varies with the object size.

Before you restore one or more Deep Cold Archive objects, you must create the XML file config.xml locally and configure the following parameters in the file:

<RestoreRequest>
    <Days>3</Days>
    <JobParameters>
        <Tier>Standard</Tier>
    </JobParameters>
</RestoreRequest>

The following table describes the parameters.

Parameter

Description

Days

The duration for which you want to keep the restored Deep Cold Archive object in the restored state. Unit: days.

Valid values: 1 to 365.

Tier

The restoration mode of the Deep Cold Archive object.

Valid values:

Expedited: The object is restored within 12 hours.
Standard: The object is restored within 48 hours.

Restore a single Deep Cold Archive Object
The following command provides an example on how to restore the exampleobject.jpg in the examplebucket bucket within 48 hours and keep the object in the restored state for three days based on the configurations specified in the config.xml file:
```
ossutil restore oss://examplebucket/exampleobject.jpg config.xml
```
Restore multiple Deep Cold Archive objects at a time
- Example 1: Restore multiple Deep Cold Archive objects in different directories
  Assume that you want to restore the following Deep Cold Archive objects in different directories of the examplebucket bucket: exampleobject1.jpg in the root directory, exampleobject2.png in the dir1/ directory, and exampleobject3.txt in the dir2/ directory. You must perform the following steps to restore the objects:
  1. Write the names of the Deep Cold Archive objects to the localfile.txt file.
```
exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt
```
  2. Restore the objects.
    The following command provides an example on how to restore multiple Deep Cold Archive objects in the examplebucket bucket within 48 hours by using the --object-file option and retain the objects in the restored state for three days based on the configurations specified in the config.xml file:
```
ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml
```
- Example 2: Restore multiple Deep Cold Archive objects in the same directory
  - Method 1
    The steps to restore multiple Deep Cold Archive objects in the same directory of a bucket are similar to the steps described in Example 1: Restore multiple Deep Cold Archive objects in different directories.
  - Method 2
    The following command provides an example on how to restore all Deep Cold Archive objects in the dest directory of examplebucket by using the -r option:
```
ossutil restore oss://examplebucket/dest -r config.xml
```
Sample output
If the preceding command is successful, a line similar to the following one is included in the command output to indicate the restoration time consumed:
```
0.106852(s) elapsed
```

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to restore an object named exampletest.png in the testbucket bucket located in the China (Shanghai) region and owned by another Alibaba Cloud account:

ossutil restore oss://testbucket/exampletest.png -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.

References

For more information about how to check whether an object is restored, see stat.
For more information about how to permanently retain an object in the restored state, see What do I do to make an object permanently in the restored state?