All Products
Search
Document Center

Object Storage Service:RestoreObject

Last Updated:Jun 08, 2023

Restores an Archive object or a Cold Archive object.

Process

The following restoration process applies to both an Archive object and a Cold Archive object:

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

  • A RestoreObject operation on an object in the restoring state fails and returns a 409 error. After an object is restored, you can successfully perform 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 the specified version of an object.

Billing

  • You are charged for restoring Archive and Cold Archive objects. For more information, see Data processing fees.

  • The restored state of an Archive object can last for up to 7 days, and that of a Cold Archive object can last for up to 365 days.

  • After the duration of 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.

  • When you restore a Cold Archive object, a Standard replica of the object is generated for temporary access. You are charged the temporary storage fees of the replica for the duration during which the replica is available based on 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

The request headers involved in this API operation include only common request headers. For more information, see Common HTTP headers.

Request parameters

Parameter

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

Specifies the duration within which the restored Archive object or Cold Archive object remains in the restored state.

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

  • Valid values for Cold Archive objects: 1 to 365. Unit: day.

Parent nodes: RestoreRequest

JobParameters

Container

No

N/A

The container that stores the restoration priority. This parameter takes effect only when you send the request to restore 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 Cold Archive objects. Valid values:

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

Parent nodes: JobParameters

Response headers

Header

Type

Example

Description

x-oss-object-restore-priority

String

Standard

The restoration priority. The header is displayed only when you send the request to restore a 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 HTTP headers.

Examples

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

    Sample requests

    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 success responses

    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 requests

    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 success responses

    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 requests

    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 success responses

    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 object in the restored state

    Sample requests

    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 success responses

    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 requests

    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 success responses

    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

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 storage class of the specified object is not Archive or Cold Archive.

NoSuchKey

404

The specified object does not exist.

RestoreAlreadyInProgress

409

The RestoreObject operation is called and the server is performing the restore operation. Do not repeatedly call the RestoreObject operation.