All Products
Search
Document Center

Object Storage Service:RestoreObject

Last Updated:Jan 30, 2024

You can access Archive objects if you enable real-time access of Archive objects or after you restore them. Real-time access is not supported for Cold Archive and Deep Cold Archive objects. You can access Cold Archive and Deep Cold Archive objects only after you restore them. In most cases, the restoration of an Archive object requires several minutes to complete, the restoration of a Cold Archive object requires several hours to complete, and the restoration of a Deep Cold Archive object requires 12 to 48 hours to complete. The given amounts of restoration time are for references. The restoration time may vary based on actual scenarios. This topic describes how to call the RestoreObject operation to restore Archive, Cold Archive, and Deep Cold Archive objects.

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.

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 the RestoreObject operation on an Archive object, a Cold Archive object, or a Deep Cold Archive object for the first time, HTTP 202 status code is returned. When you call the RestoreObject operation on an object that is restored, 200 OK is returned.

  • A RestoreObject operation on an object in the restoring state fails with an HTTP 409 error code. After an object is restored, you can successfully call another RestoreObject operation on the object.

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

Billing rules

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

  • An Archive object can remain in the restored state for up to seven days and 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 again during the process.

  • After the duration of the restored state of an object 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.

  • You are charged for Archive objects based on billing rules for Archive objects during and after the restoration.

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

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 involved in this API operation include only common request headers. For more information, see Common request headers.

Request parameters

Header

Type

Required

Example

Description

RestoreRequest

Container

Yes

N/A

The container that stores information about the RestoreObject request.

Child nodes: Days and JobParameters

Days

Integer

Yes

2

The duration within which the object remains in the restored state.

  • Valid values for Archive objects: 1 to 7. Unit: days.

  • Valid values for Cold Archive and Deep Cold Archive objects: 1 to 365. Unit: days.

Parent nodes: RestoreRequest

JobParameters

Container

No

N/A

The container that stores the restoration priority. This parameter is valid only when you restore Cold Archive or Deep Cold Archive objects.

If you do not specify the JobParameters parameter, the default restoration priority Standard is used.

Parent nodes: RestoreRequest

Child nodes: Tier

Tier

String

No

Standard

The restoration priority of a Cold Archive or Deep Cold Archive object. Default value: Standard. Valid values:

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

Parent nodes: JobParameters

Response headers

Header

Type

Example

Description

x-oss-object-restore-priority

String

Standard

The restoration priority. This header is displayed only for the Cold Archive or Deep Cold Archive object in the restored state.

x-oss-version-id

String

CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh****

The version ID of the object. This header is displayed only when a version ID of the object is specified in the request.

The response headers involved in this API operation include 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 e1Unnbm1rg****:y4eyu+4yje5ioRCr****

    Sample 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 e1Unnbm1rg****:21qtGJ+ykDVmdy4eyu+N****

    Sample 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 e1Unnbm1rg****:u6O6FMJnn+WuBwbByZxm1+y4eyu+N****
    <RestoreRequest>
      <Days>2</Days>
    </RestoreRequest>

    Sample 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 LTAI4FjmjjhjiYK6kMaV****:Gi1x7YHqTw+NQCJo0fKBHcYQ****
    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 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 o3shiyktjw1****:2JND5qqlAlaA1/kLO4kBbGTw****

    Sample 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

SDKs

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

Error codes

Error code

HTTP status code

Description

OperationNotSupported

400

The object cannot be restored because the storage class of the object is not Archive, Cold Archive, or Deep Cold Archive.

NoSuchKey

404

The specified object does not exist.

RestoreAlreadyInProgress

409

The RestoreObject operation is in progress. Do not repeatedly call the RestoreObject operation.

References