Before you access Archive or Cold Archive objects, you must run the restore command to restore the objects.

Notice
  • This topic provides sample command lines that are based 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 status of Archive or Cold Archive objects during restoration and how you are charged for object restoration, see Restore objects.

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 that you can configure to run the restore command.

Parameter Description
bucketname The name of the bucket in which the objects to restore are stored.
prefix The resources that are stored in the bucket, such as directories and objects.
local_xml_file The local XML file used to store parameters that you can configure to restore Cold Archive objects.
--encoding-type The method that is used to encode the value of the prefix parameter. Valid value: url. If you do not specify this parameter, the value of the prefix parameter is not encoded.
--payer The payer of the traffic and request fees incurred when the command is run. If you want the requester who wants to access the resources in the specified path to pay for 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 the operation that is forcibly performed without prompts.
--object-file This parameter is used to restore multiple Archive or Cold Archive objects at the same time. You must perform the following steps to use this parameter:
  1. Specify a local TXT or XML file. Then, enter the names of all objects that you want to restore in the file and separate the names with line feeds.
  2. Set --object-file to the name of the specified 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 an error occurs when one of the objects is being restored, ossutil records the error information about the object in the report file and restores 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 parameter must be used together with the -r, --recursive or --object-file parameter.
--disable-ignore-error Specifies that errors are not ignored during batch operations.
--retry-times The number of retries after the command fails to be run. Valid values: 1 to 500. Default value: 10.
-j, --job The number of concurrent tasks performed across multiple objects. Valid values: 1 to 10000. Default value: 3.

Restore one or more Archive objects

OSS takes 1 minute to restore an Archive object. An object cannot be read while it 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. This way, You can extend the period of time during which an object can remain in the restored state to up to seven days. After the period, the object returns to the frozen state.

  • Restore a single archived object
    • You can run the following command to restore an Archive object named exampleobject.txt in a bucket named examplebucket:
      ./ossutil64 restore oss://examplebucket/exampleobject.txt
    • You can run the following command to restore the specified version of an object named exampleobject.txt in a bucket named examplebucket:
      ./ossutil64 restore oss://examplebucket/exampleobject.txt --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****

      For more information about how to query all versions of an object, see Is.

  • Restore multiple Archive objects
    • Example 1: Restore multiple Archive objects in different directories
      In this example, you want to restore the following Archive objects in different directories within a bucket named examplebucket: an object named exampleobject1.jpg in the root directory, an object named exampleobject2.png in the dir1/ directory, and an object named exampleobject3.txt in the dir2/ directory. You must perform the following steps to restore the objects:
      1. Write the names of multiple Archive objects that you want to restore to the localfile.txt file.
        exampleobject1.jpg
        dir1/exampleobject2.png
        dir2/exampleobject3.txt
      2. Restore multiple 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/
    • Example 2: Restore multiple Archive objects in the same directory
      • Method 1

        For more information about how to restore multiple Archive objects of the same directory in a bucket, see Example 1: Restore multiple Archive objects in different directories.

      • Method 2
        The following command provides an example on how to restore all Archive objects of a specified directory in examplebucket by using the -r parameter:
        ./ossutil64 restore oss://examplebucket/dest -r
  • Returned results

    If the preceding commands run successfully, a command output similar to the following one is returned to indicate the time used to restore the Archive objects:

    0.106852(s) elapsed

Restore Cold Archive objects

Notice The time required to restore an object varies with the object size.

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

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

The following table describes the parameters that you can configure.

Parameter Description
Days The duration for which the restored Cold Archive object remains 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

    Specify that the object named exampleobject.jpg in examplebucket is restored within 1 hour and remains in the restored state for three days based on the configurations specified by the config.xml file.

    ./ossutil64 restore oss://examplebucket/exampleobject.jpg config.xml
  • Restore multiple Cold Archive objects
    • Example 1: Restore multiple Cold Archive objects in different directories
      In this example, you want to restore the following Cold Archive objects in different directories within a bucket named examplebucket: an object named exampleobject1.jpg in the root directory, an object named exampleobject2.png in the dir1/ directory, and an object named exampleobject3.txt in the dir2/ directory. You must perform the following steps to restore the objects:
      1. 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.txt
      2. Restore the objects.

        The following command provides an example on how to restore multiple Cold Archive objects in examplebucket by using the --object-file parameter. You can specify that the objects are restored within 1 hour and remain in the restored state for three days based on the configurations specified by 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

        For more information how to restore multiple Cold Archive objects in the same directory within a bucket, see 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 a specified directory within examplebucket by using the -r parameter:
        ./ossutil64 restore oss://examplebucket/dest -r config.xml
  • Returned results

    If the preceding commands run successfully, a command output similar to the following one is returned to indicate the time used to restore the Archive objects:

    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 a bucket named testbucket, which is 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 specify in the sync command, see Common options.