You can call this operation to restore an archived object or a cold archived object.

Versioning

Different versions of an object may have different storage classes. By default, RestoreObject restores the current version of an object. To restore a specific version of the object, specify the version ID.

Note
  • The RestoreObject operation applies only to archived objects or cold archived objects. This operation does not apply to standard or Infrequent Access (IA) objects.
  • When RestoreObject is called on an object for the first time, HTTP status code 202 is returned.
  • When you call RestoreObject that was called on a frozen object whose restored state expires, 200 OK is returned.

Restore objects

  • Restore an archived object
    The status of an archived object throughout the restoration process is described as follows:
    1. By default, the archived object is in the frozen state.
    2. After you submit a restore request, the object is in the restoring state. It takes about one minute to complete the restore task.
    3. After the server completes the restore task, the object enters the restored state and you can read the object. By default, the restored state lasts 24 hours and can be extended by another 24 hours after you call RestoreObject again. During one restoration process, RestoreObject can be called on an object for up to seven times. In other words, an object can remain in the restored state for up to seven days.
    4. After the restored state expires, the object returns to the frozen state.
  • Restore a cold archived object

    The status of a cold archived object throughout the restoration process is described as follows:

    1. By default, the cold archived object is in the frozen state.
    2. After you submit a restore request, the object is in the restoring state. The time used to restore a cold archived object is determined based on one of the following restore modes:
      • 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 restore mode is Standard.
      • Bulk: The object is restored within five to eleven hours.
    3. After the server completes the restore task, the object enters the restored state and you can read the object. You can specify the duration for which the object can remain in the restored state, which ranges from one to seven days.
    4. After the restored state expires, the object returns to the frozen state.

Billing

The fees generated when an object is converted between different states are described as follows:

  • Data retrieval fees are generated 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 generated.
  • After the restored state expires, the object returns to the frozen state. Data retrieval fees are generated if you perform the restore operation on the object again.

Request syntax

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

Examples

  • Submit a restore request for an archived 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 e1Unnbm1rgdnpI: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
  • Submit a restore request for an archived 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 e1Unnbm1rgdnpI: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.200. ***</HostId>
    </Error>
  • Submit a restore request for an archived 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 e1Unnbm1rgdnpI:u6O6FMJnn+WuBwbByZxm1+y4eyu+N****
    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
  • Submit a restore request for a cold archived 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 LTAI4FjmjjhjiYK6kMaVmKkf: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 when you call the restore operation on 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 o3shiyktjw16xw1: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

SDKs

The SDKs of the RestoreObject operation for various programming languages are as follows:

Error codes

Error code HTTP status code Description
NoSuchKey 404 The error message returned because the specified object does not exist.
OperationNotSupported 400 The error message returned because the storage class of the specified object is not Archive or Cold Archive.
RestoreAlreadyInProgress 409 The error message returned because the RestoreObject operation is called while the server is performing the restore operation. Do not call RestoreObject repeatedly.