Restores an Archive object or a Cold Archive object.

Versioning

Different versions of an object can be stored as different storage classes. By default, when you call RestoreObject to restore 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 the object.

Note
  • The RestoreObject operation applies only to Archive objects or Cold Archive objects. This operation does not apply to Standard objects or Infrequent Access (IA) objects.
  • The first time RestoreObject is called on an object, HTTP status code 202 is returned.
  • When you call RestoreObject on an object that has been restored, 200 OK is returned.

Restoration

If you want 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 takes several hours to restore a Cold Archive object.

The following section describes the status of an Archive object or a Cold Archive object throughout the restoration process:
  1. By default, an Archive object is in the frozen state before restoration.
  2. After you submit a restore request, the object is in the restoring state.
  3. After the server completes the restore task, the object enters the restored state and you can read the object.

    For Archive objects, the restored state lasts 24 hours by default. During the 24 hours, if you call RestoreObject again, the restored state is extended by 24 hours. You can prolong the restored state up to seven days by calling RestoreObject six times during the first 24 hours of restored state. You can also configure the duration of the restored in days by calling RestoreObject once. You can specify a duration of at most seven days.

    For Cold Archive objects, you can specify the duration of restored state and restoration priority. The duration of the restored state must be at least one day and at most seven days. The time required to restore a Cold Archive object to the readable state is determined based on the restoration priority of the object:
    • Expedited: The object is restored within one hour.
    • Standard: The object is restored within two to five hours. If the JobParameters element is not passed in, the default restoration priority is Standard.
    • Bulk: The object is restored within five to twelve hours.
  4. After the restored state expires, the object returns to the frozen state.

Billing description

The following section describes fees incurred when an object is converted between different states:

  • Data retrieval fees are incurred when the restore operation is performed on a frozen object.
  • The restored state can be extended to up to seven days. During this period, data retrieval fees are not incurred.
  • After the restored state expires, the object returns to the frozen state. Data retrieval fees are incurred if you perform the restore operation on the object again.

Request structure

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 contain only common request headers. For more information, see Common request headers.

Request parameters

Parameter Type Required Example Description
RestoreRequest Container Yes N/A Stores the information about the restore request.

Child nodes: Days and JobParameters

Days Integer Yes 2 Specifies the number of days that the object is in the restored state. Valid values: 1 to 7.

Parent nodes: RestoreRequest

JobParameters Container No N/A Stores the restoration priority. The configuration of this parameter takes effect only when the request is sent to restore Cold Archive objects.

If the JobParameters element is not passed in, the default restoration priority Standard is used.

Parent nodes: RestoreRequest

Child nodes: Tier

Tier String Yes Standard Specifies the restoration priority. Valid values:
  • Expedited: The object is restored within one hour.
  • Standard: The object is restored within two to five hours.
  • Bulk: The object is restored within five to twelve hours.

Parent nodes: JobParameters

Response headers

Header Type Example Description
x-oss-object-restore-priority String Standard Indicates the restoration priority. The field is displayed only when the request is sent to restore a Cold Archive object in the restored state.
x-oss-version-id String CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh**** Indicates the version ID of the object. This field 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

  • Submit a restore 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 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
  • Send a restore 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 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>
  • Send a restore 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 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
  • Send a restore 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 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 of an object when you call RestoreObject
    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 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

SDK

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 error message returned because the storage class of the specified object is not Archive or Cold Archive.
NoSuchKey 404 The error message returned because the specified object does not exist.
RestoreAlreadyInProgress 409 The error message returned because the RestoreObject operation is called while the server is performing a restore operation. Do not repeatedly call RestoreObject.