restore-object - - Alibaba Cloud Documentation Center

The restore-object command is used to restore Archive or Cold Archive objects.

Usage notes

By default, an Alibaba Cloud account has the permissions to restore objects. Restoring objects as a RAM user or by using Security Token Service (STS) requires oss:RestoreObject permission. For more information, see Attach a custom policy to a RAM user.
The restore-object command applies only to Archive objects or Cold Archive objects. This command does not apply to Standard objects or Infrequent Access (IA) objects.
To read an Archive object or a Cold Archive object, you must restore the object in advance. It takes several minutes to restore an Archive object and several hours to restore a Cold Archive object.

Billing

Storage fees, data retrieval fees and API operation calling fees are incurred when you restore objects. In addition, temporary storage fees are incurred when you restore Cold Archive and Deep Cold Archive objects.

Storage fees: You are charged storage fees based on billing rules for Archive, Cold Archive, and Deep Cold Archive objects during and after the restoration. For more information, see Storage fees.
You are charged data retrieval fees based on the size of the restored Archive, Cold Archive, or Deep Cold archive objects. For more information, see Data processing fees.
API operation calling fees:
- You are charged API operation calling fees based on the number of PUT requests when you restore Archive objects. For more information, see API operation calling fees.
- You are charged data retrieval requests when you restore Cold Archive or Deep Cold Archive objects. For more information, see API operation calling fees.
Temporary storage fees: When you restore a Cold Archive or Deep Cold Archive object, a Standard replica of the object is generated for temporary access. You are charged for the temporary storage of the replica based on the Standard storage class until the Cold Archive or Deep Cold Archive object returns to the frozen state. For more information, see Temporary storage fees.

Process

The following restoration process applies to Archive, Cold Archive, and Deep Cold Archive objects:

Initially, the object is in the frozen state.
After a request is submitted to restore the object, the object enters the restoring state.
After the OSS server completes the restoration task, the object enters the restored state and can be accessed.
You can initiate another restoration request on the object in the restored state to extend the duration of the restored state of the object. The duration of the restored state of an object cannot exceed the maximum duration supported for the corresponding storage class.
After the duration of the restored state ends, the object returns to the frozen state.

Restoration time

The following table describes the time required to restore objects in different storage classes. The given amounts of restoration time are for references. The restoration time may vary based on actual scenarios.

Storage class	Restoration time
Archive	1 minute
Cold Archive	Expedited: within 1 hour Standard: 2 to 5 hours Bulk: 5 to 12 hours
Deep Cold Archive	Expedited: within 12 hours Standard: within 48 hours

Reference value for the amounts of retrieved objects

Reference value for the amount of retrieved Cold Archive objects within an Alibaba Cloud account in one region: In a single region, an Alibaba Cloud account can retrieve an average of 500 Cold Archive objects per second. The total amount of retrieved data for the preceding priorities ranges from 100 TB to 120 TB per day. If you have higher requirements, contact technical support.
Reference value for the amount of retrieved deep Cold Archive objects within an Alibaba Cloud account in one region: In a single region, an Alibaba Cloud account can retrieve an average of 100 Deep Cold Archive objects per second. The total amount of retrieved data for the preceding priorities ranges from 10 TB to 15 TB per day. If you have higher requirements, contact technical support.

Note

After the reference value for the amounts of retrieved Cold Archive and Deep Cold Archive objects is exceeded, you can still submit a restore request. The restore request is queued, and the time that the restore task takes to complete may be longer than the expected time that corresponds to the selected priority.

Duration of the restored state

The following table describes the duration of the restored state of objects in different storage classes.

Storage class	Duration of the restored state
Archive	An integer from 1 to 7. Unit: days.
Cold Archive	An integer from 1 to 365. Unit: days.
Deep Cold Archive	An integer from 1 to 365. Unit: days.

Command syntax

ossutil api restore-object --bucket value --key value [flags]

Parameter	Type	Description
--bucket	string	Name of the bucket.
--key	string	Full path of the object.
--restore-request	string	Request information of the restoration.
--version-id	string	Version ID of the object that you want to restore.

Note

The restore-object command corresponds to the RestoreObject operation. For more information about the parameters in the RestoreObject operation, see RestoreObject.

--restore-request

The --restore-request configuration option supports both XML and JSON formats. If the value of the option contains the 'file://' prefix, configuration parameters are read from the specified file.

XML format:

<RestoreRequest>
  <Days>integer</Days>
  <JobParameters>
    <Tier>string</Tier>
  </JobParameters>
</RestoreRequest>

JSON format:

{
  "Days": integer,
  "JobParameters": {
    "Tier": "string"
  }
}

Note

For more information about supported global command-line options, see Command-line options.

Examples

Restore an Archive object

Restore an Archive object named exampleobject in examplebucket.

Create a configuration file named restore-request.xml and add the following code:

<?xml version="1.0" encoding="UTF-8"?>
<RestoreRequest>
  <Days>2</Days>
</RestoreRequest>

Sample command:

ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.xml

Create a configuration file named restore-request.json and add the following code:

{
  "Days": "2"
}

Sample command:

ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.json

Configure parameters in the following command in the JSON format:

ossutil api restore-object  --bucket examplebucket --key exampleobject --restore-request "{\"Days\":\"2\"}"

Restore Cold Archive and Deep Cold Archive objects

Restore a Cold Archive object named exampleobject in examplebucket.

Create a configuration file named restore-request.xml and add the following code:

<?xml version="1.0" encoding="UTF-8"?>
<RestoreRequest>
  <Days>2</Days>
  <JobParameters>
    <Tier>Standard</Tier>
  </JobParameters>
</RestoreRequest>

Sample command:

ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.xml

Create a configuration file named restore-request.json and add the following code:

{
  "Days": "2",
  "JobParameters": {
    "Tier": "Standard"
  }
}

Sample command:

ossutil api restore-object --bucket examplebucket --key exampleobject --restore-request file://restore-request.json

Configure parameters in the following command in the JSON format:

ossutil api restore-object  --bucket examplebucket --key exampleobject --restore-request "{\"Days\":\"2\",\"JobParameters\":{\"Tier\":\"Standard\"}}"

Related API operation

The restore-object command corresponds to the RestoreObject operation. For more information, see RestoreObject.