Object Storage Service:RestoreObject

Prerequisites

• The storage class of the object that you want to restore is Archive, Cold Archive, or Deep Cold Archive. For more information, see Overview.

• You are granted the oss:RestoreObject permission. For more information, see Attach a custom policy to a RAM user.

Usage notes

• The RestoreObject operation applies only to Archive, Cold Archive, and Deep Cold Archive objects. This operation does not apply to Standard or Infrequent Access (IA) objects.

• When you call non-access operations, such as DeleteObject, DeleteMultipleObjects, GetObjectMeta, and HeadObject, on Archive, Cold Archive, and Deep Cold Archive objects, you do not need to restore the objects. For the preceding operations, unnecessary fees are generated if the objects are restored.

• The first time you call the RestoreObject operation on an Archive object, a Cold Archive object, or a Deep Cold Archive object, the HTTP status code 202 is returned. When you call the RestoreObject operation on an object that is restored, 200 OK is returned.

• If you call the RestoreObject operation on an object in the restoring state, the operation fails and the HTTP status code 409 is returned. After the object is restored, you can call the RestoreObject operation on the object again.

• In a versioning-enabled bucket, the storage classes of different versions of an object can be different. By default, when you call the RestoreObject operation on an object, the current version of the object is restored. You can specify a version ID in the request to restore a specific version of an object.

Process

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

1. Initially, the object is in the frozen state.

2. After a request is submitted to restore the object, the object enters the restoring state.

3. After the OSS server completes the restoration task, the object enters the restored state and can be accessed.

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

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

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.

Duration of the restored state

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

Billing rules

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

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

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

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

• An Archive object can remain in the restored state for up to seven days. A Cold Archive or Deep Cold Archive object can remain in the restored state for up to 365 days. You are not charged data retrieval fees when an object is in the restored state.

• After the period of time during which an object is in the restored state ends, the object returns to the frozen state. If you restore the object after it returns to the frozen state, you are charged data retrieval fees.

Request syntax

POST /ObjectName?restore HTTP/1.1
Host: archive-bucket.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

The request headers in a RestoreObject request are only common request headers. For more information, see Common request headers.

Request parameters

Response headers

The response to a RestoreObject request contains common response headers. For more information, see Common response headers.

Examples

• Initiate a RestoreObject request for an Archive object in the frozen state for the first time

  Sample request

  POST /oss.jpg?restore HTTP/1.1
  Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  Date: Sat, 15 Apr 2017 07:45:28 GMT
  Authorization: OSS qn6q**************:77Dv****************

  Sample success response

  HTTP/1.1 202 Accepted
  Date: Sat, 15 Apr 2017 07:45:28 GMT
  Content-Length: 0
  Connection: keep-alive
  Server: AliyunOSS
  x-oss-request-id: 5374A2880232A65C23002D74

• Initiate a RestoreObject request for an Archive object in the restoring state

  Sample request

  POST /oss.jpg?restore HTTP/1.1
  Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  Date: Sat, 15 Apr 2017 07:45:29 GMT
  Authorization: OSS qn6q**************:77Dv****************

  Sample success response

  HTTP/1.1 409 Conflict
  Date: Sat, 15 Apr 2017 07:45:29 GMT
  Content-Length: 556
  Connection: keep-alive
  Server: AliyunOSS
  x-oss-request-id: 5374A2880232A65C23002D74
  <?xml version="1.0" encoding="UTF-8"?>
  <Error>
    <Code>RestoreAlreadyInProgress</Code>
    <Message>The restore operation is in progress.</Message>
    <RequestId>58EAF141461FB42C2B000008</RequestId>
    <HostId>10.101.XX.XX</HostId>
  </Error>

• Initiate a RestoreObject request for an Archive object in the restored state

  Sample request

  POST /oss.jpg?restore HTTP/1.1
  Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  Date: Sat, 15 Apr 2017 07:45:29 GMT
  Authorization: OSS qn6q**************:77Dv****************
  <RestoreRequest>
    <Days>2</Days>
  </RestoreRequest>

  Sample success response

  HTTP/1.1 200 Ok
  Date: Sat, 15 Apr 2017 07:45:30 GMT
  Content-Length: 0
  Connection: keep-alive
  Server: AliyunOSS
  x-oss-request-id: 5374A2880232A65C23002D74

• Initiate a RestoreObject request for a Cold Archive or Deep Cold Archive object in the restored state

  Sample request

  POST /coldarchiveobject?restore HTTP/1.1
  Host: cold-archive-bucket.oss-cn-hangzhou.aliyuncs.com
  User-Agent: aliyun-sdk-go/v2.1.0 (Darwin/17.5.0/x86_64;go1.11.8)/ossutil-v1.6.12
  Content-Length: 99
  Authorization: OSS qn6q**************:77Dv****************
  Content-Type: text/plain; charset=utf-8
  Date: Tue, 21 Apr 2020 11:09:19 GMT
  Accept-Encoding: gzip
  <RestoreRequest>
    <Days>2</Days>
    <JobParameters>
      <Tier>Standard</Tier>
    </JobParameters>
  </RestoreRequest>

  Sample success response

  HTTP/1.1 200 OK
  Server: AliyunOSS
  Date: Tue, 21 Apr 2020 11:09:19 GMT
  Content-Length: 0
  Connection: keep-alive
  x-oss-request-id: 5E9ED45F093E2F3930318EA0
  x-oss-object-restore-priority: Standard
  x-oss-server-time: 10

• Specify the version ID when you call the RestoreObject operation to restore an object

  Sample request

  POST /oss.jpg?restore&versionId=CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh**** HTTP/1.1
  Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  Date: Tue, 09 Apr 2019 06:50:48 GMT
  Authorization: OSS qn6q**************:77Dv****************

  Sample success response

  HTTP/1.1 202 Accepted
  Date: Tue, 09 Apr 2019 06:50:48 GMT
  Content-Length: 0
  Connection: keep-alive
  Server: AliyunOSS
  x-oss-version-id: CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh****
  x-oss-request-id: 5CAC40C8B7AEADE017000653

SDK

You can use OSS SDKs for the following programming languages to call the RestoreObject operation:

• Java

• Python

• PHP

• Go

• C

• C++

• .NET

• Android

• iOS

• Node.js

Error codes

References

• For more information about the amount of time required for restoration and the number of days in which an object remains in the restored state, see Restore objects.

• For more information about how to use ossutil to restore an object, see restore.

• For more information about how to permanently retain an object in the restored state, see What do I do to make an object permanently in the restored state?