restore-object - Object Storage Service - Alibaba Cloud Documentation Center

The restore-object command restores Archive or Cold Archive objects.

Usage notes

By default, an Alibaba Cloud account has the permission to restore objects. To restore objects as a Resource Access Management (RAM) user or using a Security Token Service (STS) token, you must have the oss:RestoreObject permission. For more information, see Attach a custom policy to a RAM user.
The restore-object command applies only to Archive or Cold Archive objects. This command does not apply to Standard or Infrequent Access (IA) objects.
To read an Archive or Cold Archive object, you must first restore the object. Restoring an Archive object takes about one minute. Restoring a Cold Archive object can take several hours.

Billing

Restoring objects incurs storage fees, data retrieval fees, and request fees. If you restore Cold Archive or Deep Cold Archive objects, temporary storage fees are also incurred.

Storage fees: Storage fees are calculated for Archive, Cold Archive, and Deep Cold Archive objects based on their respective storage classes during and after restoration. For more information, see Storage fees.
Data retrieval fees: Restoring Archive, Cold Archive, or Deep Cold Archive objects incurs data retrieval fees. For more information, see Data processing fees.
Request fees:
- Restoring Archive objects incurs fees for PUT requests. For more information, see Request fees.
- Restoring Cold Archive or Deep Cold Archive objects incurs fees for retrieval requests. For more information, see Request fees.
Temporary storage fees: When you restore a Cold Archive or Deep Cold Archive object, a replica of the object is created to allow access. This replica incurs temporary storage fees at the rate for the Standard storage class until the restored state expires. 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 you submit a request 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 an object in the restored state to extend the duration of the restored state. The duration of the restored state 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 without changing its storage class.

Restoration time

The following table describes the time required to restore objects in different storage classes. The given restoration times are for reference. Actual restoration time may vary based on specific scenarios.

Storage class	Description
Archive	1 minute.
Cold Archive	Expedited: The object is restored within 1 hour. Standard: The object is restored within 2 to 5 hours. Bulk: The object is restored within 5 to 12 hours.
Deep Cold Archive	Expedited: The object is restored within 12 hours. Standard: The object is restored within 48 hours.

Restoration quotas

The reference quota for restoring Cold Archive objects for an Alibaba Cloud account in a region: an average of 500 objects per second, and a total of 100 TB to 120 TB per day for all three restore priorities.If your business requires a higher restoration quota, contact technical support.
The reference quota for restoring Deep Cold Archive objects for an Alibaba Cloud account in a region: an average of 100 objects per second, and a total of 10 TB to 15 TB per day for both restore priorities.If your business requires a higher restoration quota, contact technical support.

Note

You can still submit restoration requests after the reference quotas for Cold Archive and Deep Cold Archive objects are exceeded. The restore request is queued, and the time required to complete the restore task may be longer than the expected time corresponding to the selected priority.

Duration of the restored state

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

Storage class	Description
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	The name of the bucket.
--key	string	The full path of the object.
--restore-request	string	The restoration request information.
--version-id	string	The version ID of the object that you want to restore.

Note

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

--restore-request

The --restore-request configuration option supports both XML and JSON syntax. If the option value contains the file:// prefix, the configuration is read from the specified local file.

XML syntax:

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

JSON syntax:

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

Note

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

Examples

Restore an Archive object

The following examples show how to restore an Archive object named exampleobject from the examplebucket bucket.

Use an XML configuration file. The following code shows the content of restore-request.xml:

<?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

Use a JSON configuration file. The following code shows the content of restore-request.json:

{
  "Days": "2"
}

Sample command:

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

Use JSON configuration parameters. Sample command:

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

Restore a Cold Archive or Deep Cold Archive object

The following examples show how to restore a Cold Archive object named exampleobject from the examplebucket bucket.

Use an XML configuration file. The following code shows the content of restore-request.xml:

<?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

Use a JSON configuration file. The following code shows the content of restore-request.json:

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

Sample command:

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

Use JSON configuration parameters. Sample command:

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 API operation. For more information, see RestoreObject.