Restore archived objects with the ossutil restore-object command - Object Storage Service - Alibaba Cloud - Object Storage Service

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 Grant a custom policy.
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.
The restored state of an Archive object lasts for a maximum of 7 days (the Days parameter value ranges from 1 to 7). After the restored state expires, the object automatically returns to the frozen state. If you plan to perform data migration (such as cross-account or large-scale migration) after restoring the object and the migration may take more than 7 days, use CopyObject to convert the Archive object to the Standard storage class within the restoration validity period before you start the migration. This prevents migration failures caused by the object returning to the frozen state after the restored state expires.

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 Request fees.
- You are charged data retrieval requests when you restore Cold Archive or Deep Cold Archive objects. 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 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.

Restoration process

The restoration process is the same for objects of different storage classes. The process is as follows.

Initially, the object is in the frozen state.
After you submit a restoration request, the object enters the restoring state.
After the server-side task is complete, the object enters the restored state. You can then read the object.
If you submit another restoration request while the object is in the restored state, the duration of the restored state is extended. The total extended duration cannot exceed the maximum duration allowed for the storage class.
After the restored state ends, the object returns to the frozen state, and its original storage class remains unchanged.

Restoration time

The time required to restore objects of different storage classes is listed in the following table. Actual restoration times may vary.

Object storage class	Description
Archive	Typically 1 minute.
Cold Archive	Expedited: Restoration is typically complete within 1 hour. Standard: Restoration is typically complete within 2 to 5 hours. Bulk: Restoration is typically complete within 5 to 12 hours.
Deep Cold Archive	Expedited: Restoration is typically complete within 12 hours. Standard: Restoration is typically complete within 48 hours.

Restoration quota

For a single Alibaba Cloud account in a single region, the reference restoration quota for Cold Archive objects is 500 objects per second on average, and the total quota across the three restoration priorities is 100 TB to 120 TB per day. If your business requires a higher restoration quota, contact Technical Support.
For a single Alibaba Cloud account in a single region, the reference restoration quota for Deep Cold Archive objects is 100 objects per second on average, and the total quota across the two restoration priorities is 10 TB to 15 TB per day. If your business requires a higher restoration quota, contact Technical Support.

After the reference restoration quota for Cold Archive or Deep Cold Archive objects is exceeded, you can still submit restoration requests. The requests are queued, and restoration may take longer than the time associated with the specified restoration priority.

Duration of the restored state

The duration that objects can remain in the restored state varies by storage class.

Object storage class	Description
Archive	1 to 7 days.
Cold Archive	1 to 365 days.
Deep Cold Archive	1 to 365 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.