Menu
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

POST Object restore

Description

Restores a temporary copy of an archived object. You can optionally provide version ID to restore specific object version. If version ID is not provided, it will restore the current version.

In the request, you specify the number of days that you want the restored copy to exist. After the specified period, Amazon S3 deletes the temporary copy. Note that the object remains archived. Amazon S3 deletes only the restored copy.

An object in the Glacier storage class is an archived object. To access the object, you must first initiate a restore request, which restores a copy of the archived object. The time it takes restore jobs to complete depends on which retrieval option you specify, Expedited, Standard, or Bulk.

When retrieving an archived object, you can specify one of the following options in the Tier element of the request body:

  • Expedited - Expedited retrievals allow you to quickly access your data when occasional urgent requests for a subset of archives are required. For all but the largest archived object (250 MB+), data accessed using Expedited retrievals are typically made available within 1–5 minutes.

  • Standard - Standard retrievals allow you to access any of your archived objects within several hours. Standard retrievals typically complete within 3–5 hours. This is the default option for retrieval requests that do not specify the retrieval option.

  • Bulk - Bulk retrievals are Amazon Glacier lowest-cost retrieval option, enabling you to retrieve large amounts, even petabytes, of data inexpensively in a day. Bulk retrievals typically complete within 5–12 hours.

For more information about archive retrieval options and provisioned capacity for Expedited retrievals, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

You can obtain restoration status by sending a HEAD request. In the response, these operations return the x-amz-restore header with restoration status information.

After restoring an archived object, you can update the restoration period by reissuing this request with the new period. Amazon S3 updates the restoration period relative to the current time and charges only for the request—there are no data transfer charges.

You cannot issue another restore request when Amazon S3 is actively processing your first restore request for the same object. However, after Amazon S3 restores a copy of the object, you can send restore requests to update the expiration period of the restored object copy.

If your bucket has a lifecycle configuration with a rule that includes an expiration action, the object expiration overrides the life span that you specify in a restore request. For example, if you restore an object copy for 10 days but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in 3 days. For more information about lifecycle configuration, see PUT Bucket lifecycle and Object Lifecycle Management in Amazon Simple Storage Service Developer Guide.

To use this action, you must have s3:RestoreObject permissions on the specified object. For more information, see Access Control in the Amazon S3 Developer Guide.

Requests

Syntax

Copy
POST /ObjectName?restore&versionId=VersionID HTTP/1.1 Host: BucketName.s3.amazonaws.com Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) Content-MD5: MD5 <RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-3-01"> <Days>NumberOfDays</Days> <GlacierJobParameters> <Tier>RetrievalOption</Tier> </GlacierJobParameters> </RestoreRequest>

Note

The syntax shows some of the request headers. For a complete list, see the Request Headers section of this topic.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required
Content-MD5

The base64-encoded 128-bit MD5 digest of the data. This header must be used as a message integrity check to verify that the request body was not corrupted in transit. For more information, go to RFC 1864.

Type: String

Default: None

Yes

Request Elements

Name Description
RestoreRequest

Container for restore information.

Type: Container

Ancestors: AccessControlPolicy

Days

Lifetime of the restored (active) copy. The minimum number of days that you can restore an object from Amazon Glacier is 1. After the object copy reaches the specified lifetime, Amazon S3 removes the copy from the bucket. This is a required element.

Type: Positive integer

Ancestors: RestoreRequest

GlacierJobParameters

Container for Glacier job parameters. This element is not required.

Type: Container

Ancestors: RestoreRequest

Tier

The retrieval option to use when restoring the archive. Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: GlacierJobParameters

Responses

A successful operation returns either 200 OK or 202 Accepted status code.

  • If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.

  • If the object copy is previously restored, Amazon S3 returns 200 OK in the response.

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

Error Code Description HTTP Status Code SOAP Fault Code Prefix
RestoreAlreadyInProgress Object restore is already in progress. 409 Conflict Client
GlacierExpeditedRetrievalNotAvailable Glacier expedited retrievals are currently not available, please try again later. (Returned if there is insufficient capacity to process the Expedited request. This error only applies to Expedited retrievals and not to Standard or Bulk retrievals.) 503 N/A

Examples

Restore an Object for 2 Days Using the Expedited Retrieval Option

The following restore request restores a copy of the photo1.jpg object from Amazon Glacier for a period of 2 days using the expedited retrieval option.

Copy
POST /photo1.jpg?restore HTTP/1.1 Host: examplebucket.s3.amazonaws.com Date: Mon, 22 Oct 2012 01:49:52 GMT Authorization: authorization string Content-Length: content length <RestoreRequest> <Days>2</Days> <GlacierJobParameters> <Tier>Expedited</Tier> <GlacierJobParameters> </RestoreRequest>

If the examplebucket does not have a restored copy of the object, Amazon S3 returns the following 202 Accepted response.

Copy
HTTP/1.1 202 Accepted x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw= x-amz-request-id: 9F341CD3C4BA79E0 Date: Sat, 20 Oct 2012 23:54:05 GMT Content-Length: 0 Server: AmazonS3

If a copy of the object is already restored, Amazon S3 returns a 200 OK response, only updating the restored copy's expiry time.

Related Resources