RestoreObject

Prerequisites

• The object uses Archive, Cold Archive, or Deep Cold Archive storage. For more information, see Storage classes.

• You have the oss:RestoreObject permission. Attach a custom policy to a RAM user.

Notes

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

• The first time you call the RestoreObject operation for an object, a 202 Accepted response is returned. If the object is already in the restored state, subsequent calls return a 200 OK response.

• You cannot call the RestoreObject operation on an object that is currently being restored. Doing so returns a 409 Conflict error. Wait for the restoration to complete before you call the operation again.

• For a bucket with versioning enabled, different versions of an object can have different storage classes. By default, calling the RestoreObject operation restores the current version of the object. You can restore a specific version by specifying its versionId.

Restoration process

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

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

2. After you submit a restoration request, the object enters the restoring state.

3. After the server-side task is complete, the object enters the restored state. You can then read the object.

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

5. After the restored state ends, the object returns to the frozen state.

Restoration time

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

^①For a single Alibaba Cloud account in a single region, the estimated data retrieval rate for Cold Archive objects is 500 objects per second on average. The total retrieval amount across all three restoration priorities is 100 TB to 120 TB per day. If your business requires a higher retrieval rate, contact Technical Support.

^②For a single Alibaba Cloud account in a single region, the estimated data retrieval rate for Deep Cold Archive objects is 100 objects per second on average. The total retrieval amount across both restoration priorities is 10 TB to 15 TB per day. If your business requires a higher retrieval rate, contact Technical Support.

Duration of the restored state

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

Billing

• Data retrieval fees are incurred when you restore Archive, Cold Archive, and Deep Cold Archive objects. For more information, see Data processing fees.

• Archive objects can remain in the restored state for up to 7 days. Cold Archive and Deep Cold Archive objects can remain in the restored state for up to 365 days. No additional data retrieval fees are incurred during this period.

• After the restored state ends, the object returns to the frozen state. If you restore the object again, data retrieval fees are incurred.

• When you restore a Cold Archive or Deep Cold Archive object, a replica of the object is created in the Standard storage class to allow access. While the object is in the restored state, you are charged for the temporary storage of this replica at the rate of the Standard storage class. For more information, see Temporary storage fees.

Request syntax

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

Request headers

RestoreObject uses only common request headers. For more information, see Common request headers.

Request parameters

Response headers

RestoreObject responses include common response headers. For more information, see Common response headers.

Examples

• Restore a frozen Archive object (first request)

  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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  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

• Restore an Archive object that is being restored

  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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  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>

• Restore an Archive object already 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  <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

• Restore a Cold Archive or Deep Cold Archive object already 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  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

• Restore a specific object version

  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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

  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

OSS SDKs

Call RestoreObject with OSS SDKs for these languages:

• Java

• Python V2

• PHP V2

• Go V2

• C

• C++

• .NET

• Android

• iOS

• Node.js

• Harmony

• Browser.js

ossutil

For information about the ossutil command that corresponds to the RestoreObject operation, see restore-object.

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

• For more information about how to permanently retain an object in the restored state, see How to keep an OSS object permanently restored?