DocsICP FilingConsole
Documentation
Home Page Object Storage Service Developer Reference Developer tools ossutil 1.0 Common commands revert-versioning Restore Files

Use the restore command to restore objects

Updated at:
Copy as MD
Product
My Favorites

Archive objects must be restored before they can be read, unless real-time access is enabled. Real-time access is not supported for Cold Archive and Deep Cold Archive objects, which must be restored before they can be read. Restoring an Archive object typically takes several minutes, a Cold Archive object takes several hours, and a Deep Cold Archive object takes 12 to 48 hours. The actual restoration time may vary. This topic describes how to use the restore command to restore objects.

Notes

  • To restore a single object, you must have the oss:RestoreObject permission. To restore multiple objects in a folder, you must have the oss:RestoreObject and oss:ListObjects permissions. For more information, see Grant custom permissions to a RAM user.

  • Starting from ossutil 1.6.16, you can use ossutil as the binary name in the command line regardless of your operating system. If you use a version of ossutil earlier than 1.6.16, you must change the binary name based on your operating system. For more information, see ossutil command reference.

  • For more information about the restoration status and billing of Archive, Cold Archive, or Deep Cold Archive objects, see Restore objects.

  • This command is available only in 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.

Parameter

Description

bucketname

The name of the bucket.

prefix

Resources in a bucket can include folders and files.

local_xml_file

The local XML file that stores the restoration parameters for Cold Archive objects.

--encoding-type

The encoding method for the prefix. Set the value to url. If you do not specify this option, the prefix is not encoded.

--payer

The payer for the request. To have the requester pay for fees such as traffic and requests, set this option to requester.

--version-id

The version ID of the object. This option applies only to objects in buckets for which versioning is enabled or suspended.

-r, --recursive

Restores all objects that match the prefix. If you do not specify this option, ossutil restores only the specified object.

-f, --force

Forces the operation without a confirmation prompt.

--object-file

Restores multiple Archive, Cold Archive, or Deep Cold Archive objects in a batch. To use this option:

  1. Specify a local file in .txt or XML format. In the file, list all objects to restore, with each object on a new line.

  2. ossutil reads all objects from the local file and restores them in a batch.

Note

If an error occurs when restoring an object, ossutil records the error information in the report file and continues to restore the other objects. Information about successfully restored objects is not recorded in the report file.

--snapshot-path

Generates snapshots only for the objects in the current operation. If snapshots already exist for the objects, this operation is ignored.

Note

This option must be used with the -r, --recursive or --object-file option.

--disable-ignore-error

Does not ignore errors during batch operations.

--retry-times

The number of retries if an error occurs. Default value: 10. Value range: 1 to 500.

-j, --job

The number of concurrent tasks for operations on multiple objects. Default value: 3. Value range: 1 to 10000.

Restore Archive objects

Restoring an Archive object takes about one minute. You cannot read an object while it is being restored.

By default, a restored object remains in the restored state for one day. If you run the restore command on an object that is already restored, its restored state is extended by one day. The restored state can be extended for a maximum of seven days. After this period, the object returns to the frozen state.

Note

You can use the cp command to change the storage class of an object. For more information, see Copy an object and change its storage class.

When you restore an Archive object, you can also create a local XML file named config.xml to configure the number of days for the restored state.

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

  • Restore a single Archive object

    • The following example shows how to restore an Archive object named exampleobject.txt in the examplebucket bucket and keep the object in the restored state for three days.

      ossutil restore oss://examplebucket/exampleobject.txt config.xml

    • The following example shows how to restore a specific version of the 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 obtain all versions of an object, see ls (List account-level resources).

  • Restore multiple Archive objects

    • Example 1: Objects in different folders

      To restore multiple Archive objects that are in different folders of the examplebucket bucket, such as exampleobject1.jpg in the root folder, exampleobject2.png in the dir1/ folder, and exampleobject3.txt in the dir2/ folder, perform the following steps.

      1. Write the names of the Archive objects that you want to restore to the local file localfile.txt.

        exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt

      2. In the config.xml file, set the restored state to last for three days.

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

      3. Restore multiple Archive objects.

        Use the --object-file option to restore multiple Archive objects in the examplebucket bucket.

        ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

    • Example 2: Objects in the same folder

      • Method 1

        You can refer to Example 1 to restore multiple Archive objects in the same folder of a bucket.

      • Method 2

        You can use the -r option to restore all Archive objects from the specified dest folder in the examplebucket bucket.

        ossutil restore oss://examplebucket/dest -r config.xml

  • Output

    If the operation is successful, the output includes the restore request initiation time. Example:

    0.106852(s) elapsed

Restore Cold Archive objects

Important

The actual restoration time varies based on the object size.

Before you restore one or more Cold Archive objects, create a local XML file named config.xml and configure the following restore parameters in the file.

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

The following table describes the parameters.

Parameter

Description

Days

The number of days that the restored Cold Archive object remains in the restored state. Unit: days.

Value range: 1 to 365

Tier

The restoration priority for the Cold Archive object.

Valid values:

  • Expedited (high priority): 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 restores the exampleobject.jpg object in the examplebucket bucket within 1 hour and keeps the object in the restored state for three days, based on the configurations in the config.xml file.

    ossutil restore oss://examplebucket/exampleobject.jpg config.xml

  • Restore multiple Cold Archive objects

    • Example 1: Objects in different folders

      To restore multiple Cold Archive objects that are in different folders of the examplebucket bucket, such as exampleobject1.jpg in the root folder, exampleobject2.png in the dir1/ folder, and exampleobject3.txt in the dir2/ folder, perform the following steps.

      1. Write the names of the Cold Archive objects to restore to the local file localfile.txt.

        exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt

      2. Restore multiple objects.

        Use the --object-file option to restore multiple Cold Archive objects in the examplebucket bucket. Based on the configurations in the config.xml file, the objects are restored within 1 hour and kept in the restored state for three days.

        ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

    • Example 2: Objects in the same folder

      • Method 1

        You can refer to Example 1 to restore multiple Cold Archive objects in the same folder of a bucket.

      • Method 2

        Use the -r option to restore all Cold Archive objects from the dest folder of the examplebucket bucket.

        ossutil restore oss://examplebucket/dest -r config.xml

  • Output

    If the operation is successful, the output includes the time taken to initiate the restore request. For example:

    0.106852(s) elapsed

Restore Deep Cold Archive objects

Important

The actual restore time depends on the object size.

Before you restore one or more Deep Cold Archive objects, create a local XML file named config.xml and configure the following restore parameters in the file.

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

The configuration parameters are as follows:

Parameter

Description

Days

The number of days that the restored Deep Cold Archive object remains in the restored state. Unit: days.

Value range: 1 to 365

Tier

The restoration priority for the Deep Cold Archive object.

Valid values:

  • Expedited (high priority): The object is restored within 12 hours.

  • Standard: The object is restored within 48 hours.

  • Restore a single Deep Cold Archive object

    Based on the configurations in the config.xml file, the following command restores the exampleobject.jpg object in the examplebucket bucket within 48 hours and keeps it in the restored state for three days.

    ossutil restore oss://examplebucket/exampleobject.jpg config.xml

  • Restore multiple Deep Cold Archive objects

    • Example 1: Objects in different folders

      To restore multiple Deep Cold Archive objects that are in different folders of the examplebucket bucket, such as exampleobject1.jpg in the root folder, exampleobject2.png in the dir1/ folder, and exampleobject3.txt in the dir2/ folder, perform the following steps.

      1. Add the names of the Deep Cold Archive objects to be restored to the local file localfile.txt.

        exampleobject1.jpg
dir1/exampleobject2.png
dir2/exampleobject3.txt

      2. Restore multiple objects.

        Use the --object-file option to restore multiple Deep Cold Archive objects in the examplebucket bucket within 48 hours and keep them in the restored state for three days. This operation is based on the configurations in the config.xml file.

        ossutil restore oss://examplebucket --object-file localfile.txt --snapshot-path dir/ config.xml

    • Example 2: Objects in the same folder

      • Method 1

        You can refer to Example 1 to restore multiple Deep Cold Archive objects in the same folder of a bucket.

      • Method 2

        Use the -r option to restore all Deep Cold Archive objects in the dest folder of the examplebucket bucket.

        ossutil restore oss://examplebucket/dest -r config.xml

  • Output

    If the operation is successful, the output shows the time taken to initiate the restore request. For example:

    0.106852(s) elapsed

Common options

To access a bucket in a different region, use -e to specify the endpoint. To access a bucket owned by a different Alibaba Cloud account, use -i for the AccessKey ID and -k for the AccessKey secret.

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

ossutil restore oss://testbucket/exampletest.png -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret

Common options.

References

Previous：revert-versioningNext：rm