All Products
Search
Document Center

Object Storage Service:Use the restore command to restore objects

Last Updated:Jan 30, 2024

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.

Important
  • 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 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

./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 in the syntax.

Parameter

Description

bucketname

The name of the bucket.

prefix

The name of the bucket that contains the object you want to restore.

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 parameter, ossutil restores only the specified object.

-f, --force

Specifies that the restoration operation is forced 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 parameter, perform the following steps:

  1. 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.

  2. 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 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, no snapshots are generated again 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

Specifies the number of retries in case of an error. 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.

Note

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.xml
    • The 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.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. 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 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 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 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

Important

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:

  • 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

    Restore the exampleobject.jpg object in the examplebucket bucket within 1 hour and keep the object in the restored state for 3 days based on the configurations specified in the config.xml file.

    ./ossutil64 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 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:

      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 parameter and keep the object in the restored state for 3 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

Important

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:

  • Expedited: The object is restored within 12 hours.

  • Standard: The object is restored within 48 hours.

  • Restore a single Deep Cold Archive Object

    Restore the exampleobject.jpg in the examplebucket bucket within 48 hours and keep the object in the restored state for 3 days based on the configurations specified in the config.xml file.

    ./ossutil64 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 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:

      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 parameter and maintain the objects in the restored state for 3 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.

References