Before you can access Archive, Cold Archive, and Deep Cold Archive objects, you must first use the restore command to restore the objects.
This topic provides sample command lines that work on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see ossutil.
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
./ossutil64 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 syntax.
Item | Description |
bucketname | The name of the bucket that contains the object you want to restore. |
prefix | The resources that are stored 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 this parameter is not specified, the prefix is not encoded. |
--payer | The payer of the request. If you want the requester who wants to access the resources in the specified path to pay the traffic and request fees, set this parameter to requester. |
--version-id | The version ID of the object that you want to restore. This parameter applies only to objects in buckets for which versioning is enabled or suspended. |
-r, --recursive | If you specify this parameter, 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 restoration operation is forcefully performed without prompts 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. You must perform the following steps to use this parameter:
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 restoring the other objects. Information about restored objects is not recorded in the report file. |
--snapshot-path | If you specify this parameter, 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, this operation is ignored. Note This option must be used together with the -r, --recursive or --object-file option. |
--disable-ignore-error | Specifies that errors are not ignored for batch restoration. |
--retry-times | Specifies the number of retries after an error occurs when the command is run. Default value: 10. Valid values: 1 to 500. |
-j, --job | The number of concurrent tasks for a batch restoration operation. 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.
You can run the cp command to convert 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 maintain the object in the restored state for three days:
./ossutil64 restore oss://examplebucket/exampleobject.txt config.xmlThe following sample code provides an example on how to restore a specified version of an Archive object named exampleobject.txt in the examplebucket bucket:
./ossutil64 restore oss://examplebucket/exampleobject.txt --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3**** config.xmlFor more information about how to list all versions of an object, see ls.
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. Perform the following steps to restore the objects:
Write the names of the Archive objects that you want to restore to the localfile.txt file.
exampleobject1.jpg dir1/exampleobject2.png dir2/exampleobject3.txtIn the config.xml file, specify that the objects remain in the restored state for three days.
<RestoreRequest> <Days>3</Days> </RestoreRequest>Restore the Archive objects.
The following command provides an example on how to restore multiple Archive objects in examplebucket by using the --object-file parameter:
./ossutil64 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 in 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 parameter:
./ossutil64 restore oss://examplebucket/dest -r config.xml
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
The 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 mode. Valid values:
|
Restore a single Cold Archive object
Specify that the exampleobject.jpg object in the examplebucket bucket is restored within 1 hour and remains in the restored state for three days based on the configurations specified in the config.xml file.
./ossutil64 restore oss://examplebucket/exampleobject.jpg config.xmlRestore 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 within 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:
Write the names of multiple Cold Archive objects that you want to restore to the localfile.txt file.
exampleobject1.jpg dir1/exampleobject2.png dir2/exampleobject3.txtRestore 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 parameter and keep the object in the restored state for three days based on the configurations specified in the config.xml file:
./ossutil64 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 parameter:
./ossutil64 restore oss://examplebucket/dest -r config.xml
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
The 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. Valid values:
|
Restore a single Deep Cold Archive Object
Specify that exampleobject.jpg in the examplebucket bucket is restored within 48 hours and remains in the restored state for three days based on the configurations specified in the config.xml file.
./ossutil64 restore oss://examplebucket/exampleobject.jpg config.xmlRestore 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 within 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:
Write the names of the Deep Cold Archive objects to the localfile.txt file.
exampleobject1.jpg dir1/exampleobject2.png dir2/exampleobject3.txtRestore 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 parameter and maintain the objects in the restored state for three days based on the configurations specified in the config.xml file:
./ossutil64 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 within 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 within examplebucket by using the -r parameter:
./ossutil64 restore oss://examplebucket/dest -r config.xml
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, you can 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:
./ossutil64 restore oss://testbucket/exampletest.png -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****For more information about other common options that you can use for the sync command, see View options.