Restores an Archive object or a Cold Archive object.
- 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.
- When you call RestoreObject to restore an object for the first time, HTTP status code 202 is returned.
- When you call RestoreObject again to restore 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 it takes several hours to restore a Cold Archive object based on different restoration priorities. The actual restoration time prevails.
- By default, an Archive object is in the frozen state.
- After you submit a request to restore the object, the object enters the restoring state.
- After the Object Storage Service (OSS) server completes the restoration task, the object enters the restored state and can be read.
- Archive objects
For Archive objects, the restored state lasts 24 hours by default. During the 24 hours, you can call RestoreObject again to extend the duration of the restored state for another 24 hours. During one restoration process, you can call RestoreObject for up to seven times to extend the duration of the restored state of the object. In other words, an object can remain in the restored state for up to seven days. You can also configure the duration of the restored state in days by calling RestoreObject. You can specify a duration of up to seven days.
- Cold Archive objectsFor Cold Archive objects, you can specify the duration of the restored state and the restoration priority. The duration of the restored state must be at least one day and at most 365 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 parameter is not passed in, the default restoration mode is Standard.
- Bulk: The object is restored within five to twelve hours.
The reference value for the amounts of retrieved data is an average of 500 objects per second. The total amount of retrieved data for the preceding priorities ranges from 100 TB to 120 TB per day.
- Archive objects
- After the duration of the restored state expires, the object returns to the frozen state.
Usage notes
- The RestoreObject operation applies only to Archive objects or Cold Archive objects. This operation does not apply to Standard or IA objects.
- When you call RestoreObject to restore an object for the first time, HTTP status code 202 is returned.
- When you call RestoreObject to restore an object for the first time, HTTP status code 202 is returned. When you call RestoreObject to restore an object that has been restored, 200 OK is returned.
- In a versioned bucket, the storage classes of different versions of an object can be different. 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.
Billing
- Data retrieval fees are generated when you restore Archive and Cold Archive objects. For more information, see Data processing fees.
- The restored state of an Archive object can persist up to seven days and that of a Cold Archive object can persist up to 365 days. You are not repeatedly charged data retrieval fees during this process.
- After the duration of 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.
- When you restore a Cold Archive object, a Standard replica 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 Standard storage. For more information, see Temporary storage fees.
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
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 duration of the restored state for Archive and Cold Archive objects.
Parent nodes: RestoreRequest |
JobParameters | Container | No | N/A | Stores the restoration priority. This parameter takes effect only when the request is sent to restore Cold Archive objects. If the JobParameters parameter is not passed in, the default restoration priority Standard is used. Parent nodes: RestoreRequest Child nodes: Tier |
Tier | String | No | Standard | Specifies the restoration priority. Default value: Standard. Valid values:
Parent nodes: JobParameters |
Response headers
Header | Type | Example | Description |
---|---|---|---|
x-oss-object-restore-priority | String | Standard | Specifies 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**** | Specifies 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 responsesHTTP/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 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 responsesHTTP/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>
- Submit 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 responsesHTTP/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 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 responsesHTTP/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 responsesHTTP/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 the restore operation. Do not call RestoreObject repeatedly. |