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

POST Object restore

Description

This operation performs the following types of requests:

  • select – Perform a select query on an archived object

  • restore an archive – Restore an archived object

To use this operation, you must have permission to perform the s3:RestoreObject and s3:GetObject actions. The bucket owner has this permission by default and can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.

Querying Archives with Select Requests

You use a select type of request to perform SQL queries on archived objects. The archived objects that are being queried by the select request must be formatted as uncompressed comma-separated values (CSV) files. You can run queries and custom analytics on your archived data without having to restore your data to a hotter Amazon S3 tier. For an overview about select requests, see Querying Archived Objects in the Amazon Simple Storage Service Developer Guide.

When making a select request, do the following:

  • Define an output location for the output of your select query. This location must be an Amazon S3 bucket in the same AWS Region as the bucket containing the archive object that is being queried. The AWS account that initiates the job must have permissions to write to the S3 bucket. You can specify the storage class and encryption for the output objects stored in the bucket. For more information about output, see Querying Archived Objects in the Amazon Simple Storage Service Developer Guide.

    When you're setting the S3 structure in the request body, it might be helpful to read the following topics:

  • Define the SQL expression to use for the SELECT for your query in the SelectParameters structure in the request body. You can use expressions like the following examples.

    • The following expression returns all records from the specified object.

      Copy
      SELECT * FROM Object
    • Assuming that you are not using any headers for data stored in the object, you can specify columns using positional headers.

      Copy
      SELECT s._1, s._2 FROM Object s WHERE s._3 > 100
    • If you have headers and you set the fileHeaderInfo in the CSV structure in the request body to USE, you can specify headers in the query. (If you set the fileHeaderInfo field to IGNORE, the first row is skipped for the query.) You cannot mix ordinal positions with header column names.

      Copy
      SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

For more information about using SQL with Amazon Glacier select restore, see Amazon Glacier Select SQL Reference in the Amazon Glacier Developer Guide.

When making a select request, you can also do the following:

  • Specify the Expedited tier to expedite your queries. For more information about tiers, see the next section, Restoring Archives.

  • Specify details about the data serialization format of both the input object being queried and the serialization of the CSV-encoded query results.

The following are additional important facts about the select feature:

  • The output results are new Amazon S3 objects. Unlike archive retrievals, they are stored until explicitly deleted—manually or through a lifecycle policy.

  • You can issue more than one select request on the same Amazon S3 object. There is no de-duplication of the requests, so you must be careful not to issue duplicate requests.

  • A select request is accepted, even if the object has already been restored in Amazon S3. A select request doesn’t return error response 409.

Restoring Archives

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

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 finish depends on which data access tier you specify, Expedited, Standard, or Bulk.

In a restore 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.

When restoring an archived object (or using a select request), you can specify one of the following options in the Tier element of the request body:

  • Expedited – Allows 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 – Allows you to access any of your archived objects within several hours. Standard retrievals typically finish within 3–5 hours. This is the default tier.

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

For more information about archive retrieval options and provisioned capacity for Expedited data access, 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.

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 request body

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, see RFC 1864.

Type: String

Default: None

Yes

Request Elements

The following XML example shows the request body for restoring an archive.

Copy
<RestoreRequest> <Days>2</Days> <GlacierJobParameter> <Tier>Bulk</Tier> <GlacierJobParameter> </RestoreRequest>

The following table explains the XML for an archive restore in the request body.

Name Description Required
RestoreRequest

Container for restore information.

Type: Container

Yes
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 if you are restoring an archive.

Do not use with a SELECT type of request.

Type: Positive integer

Ancestors: RestoreRequest

Yes, if restoring an archive.
GlacierJobParameters

Container for Glacier job parameters.

Do not use with a SELECT type of request.

Type: Container

Ancestors: RestoreRequest

No
Tier

The data access tier to use when restoring the archive. Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: GlacierJobParameters

No

The following XML shows the request body for a select query on an archived object.

Copy
<RestoreRequest> <Type>SELECT</Type> <Tier>Expedited</Tier> <Description>Job description</Description> <SelectParameters> <Expression>Select * from Object</Expression> <ExpressionType>SQL</ExpressionType> <InputSerialization> <CSV> <FileHeaderInfo>IGNORE</FileHeaderInfo> <RecordDelimiter>\n</RecordDelimiter> <FieldDelimiter>,</FieldDelimiter> <QuoteCharacter>"</QuoteCharacter> <QuoteEscapeCharacter>"</QuoteEscapeCharacter> <Comments>#</Comments> </CSV> </InputSerialization> <OutputSerialization> <CSV> <QuoteFields>ASNEEDED</QuoteFields> <RecordDelimiter>\n</RecordDelimiter> <FieldDelimiter>,</FieldDelimiter> <QuoteCharacter>"</QuoteCharacter> <QuoteEscapeCharacter>"</QuoteEscapeCharacter> </CSV> </OutputSerialization> </SelectParameters> <OutputLocation> <S3> <BucketName>Name of bucket</BucketName> <Prefix>Key prefix</Prefix> <CannedACL>Canned ACL string</CannedACL> <AccessControlList> <Grantee> <Type>Grantee Type</Type> <ID>Grantee identifier</ID> <URI>Grantee URI</URI> <Permission>Granted permission</Permission> <DisplayNmae>Display Name</DisplayName> <EmailAddress>email</EmailAddress> </Grantee> </AccessControlList> <Encryption> <EncryptionType>Encryption type</EncryptionType> <KMSKeyId>KMS Key ID</KMSKeyId> <KMSContext>Base64-encoded JSON<KMSContext> </Encryption> <UserMetadata> <MetadataEntry> <Name>Key</Name> <Value>Value</Value> </MetadataEntry> </UserMetadata> <Tagging> <TagSet> <Tag> <Key>Tag name</Key> <Value>Tag value</Value> </Tag> </TagSet> </Tagging> <StorageClass>Storage class</StorageClass> </S3> </OutputLocation> </RestoreRequest>

The following tables explain the XML for a SELECT in the request body.

Name Description Required
RestoreRequest

Container for restore information.

Type: Container

Yes
Tier

The data access tier to use when restoring the archive. Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: RestoreRequest

No
Description

The optional description for the request.

Type: String

Ancestors: RestoreRequest

No
SelectParameters

Describes the parameters for select job request.

Type: Container

Ancestors: RestoreRequest

Yes, if request type is SELECT.
OutputLocation

Describes the location that receives the results of the select restore request.

Type: Container for Amazon S3

Ancestors: RestoreRequest

Yes, if request type is SELECT.

The SelectParameters container element contains the following elements.

Name Description Required
Expression

The SQL expression. For example:

  • The following SQL expression retrieves the first column of the data from the object stored in CSV format.

    SELECT s._1 FROM Object s

  • The following SQL expression returns everything from the object.

    SELECT * FROM Object

Type: String

Ancestors: SelectParameters

Yes
ExpressionType

Identifies the expression type.

Type: String

Valid values: SQL

Ancestors: SelectParameters

Yes
InputSerialization

Describes the serialization format of the object.

Type: Container for CSV

Ancestors: SelectParameters

Yes
OutputSerialization

Describes how the results of the select job are serialized.

Type: Container for CSV

Ancestors: SelectParameters

Yes

The CSV container element (inside InputSerialization) contains the following elements.

Name Description Required
RecordDelimiter

A single character used to separate individual records in the input. Instead of the default value, you can specify an arbitrary delimiter.

Type: String

Default: \n

Ancestors: CSV

No
FieldDelimiter

A single character used to separate individual fields in a record. You can specify an arbitrary delimiter.

Type: String

Default: ,

Ancestors: CSV

No
QuoteCharacter

A single character used for escaping when the field delimiter is part of the value.

Consider this example in a CSV file:

"a, b"

The use of quotation marks makes this value a single field because you are wrapping the value in quotation marks. If you don't specify the quotation marks, the comma is a field delimiter (which makes it two separate field values, a and b).

Type: String

Default: "

Ancestors: CSV

No
QuoteEscapeCharacter

A single character used for escaping the quotation mark character inside an already escaped value. For example, the value """ a , b """ is parsed as " a , b ".

Type: String

Default: "

Ancestors: CSV

No
FileHeaderInfo

Describes the first line in the input data. It is one of the ENUM values.

  • NONE: First line is not a header.

  • IGNORE: First line is a header, but you can't use the header values to indicate the column in an expression. You can use column position (such as _1, _2, …) to indicate the column (SELECT s._1 FROM OBJECT s).

  • Use: First line is a header, and you can use the header value to identify a column in an expression (SELECT "name" FROM OBJECT).

Type: Enum

Valid values: NONE | USE | IGNORE

Ancestors: CSV

No
Comments

A single character used to indicate that a row should be ignored when the character is present at the start of that row. You can specify any character to indicate a comment line.

Type: String

Ancestors: CSV

No

The CSV container element (inside OutputSerialization) contains the following elements.

Name Description Required
QuoteFields

Indicates whether to use quotation marks around output fields.

  • ALWAYS: Always use quotation marks for output fields.

  • ASNEEDED: Use quotation marks for output fields when needed.

Type: Enum

Valid values: ALWAYS | ASNEEDED

Default: AsNeeded

Ancestors: CSV

No
RecordDelimiter

A single character used to separate individual records in the output. Instead of the default value, you can specify an arbitrary delimiter.

Type: String

Default: \n

Ancestors: CSV

No
FieldDelimiter

A single character used to separate individual fields in a record. You can specify an arbitrary delimiter.

Type: String

Default: ,

Ancestors: CSV

No
QuoteCharacter

A single character used for escaping when the field delimiter is part of the value. For example, if the value is a, b, then Amazon S3 wraps this field value in quotation marks as follows: " a , b ".

Type: String

Default: "

Ancestors: CSV

No
QuoteEscapeCharacter

A single character used for escaping the quotation mark character inside an already escaped value. For example, if the value is " a , b ", then Amazon S3 wraps the value in quotation marks as follows: """ a , b """.

Type: String

Ancestors: CSV

No

The S3 container element (inside OutputLocation) contains the following elements.

Name Description Required
AccessControlList

A list of grants that control access to the staged results.

Type: Container for Grant

Ancestors: S3

No
BucketName

The name of the S3 bucket where the select restore results are stored. The bucket must be in the same AWS Region as the bucket that contains the input archive object.

Type: String

Ancestors: S3

Yes
CannedACL

The canned access control list (ACL) to apply to the select restore results.

Type: String

Valid values: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control

Ancestors: S3

No
Encryption

Contains encryption information for the stored results.

Type: Container for Encryption

Ancestors: S3

No
Prefix

The prefix that is prepended to the select restore results. The maximum length for the prefix is 512 bytes.

Type: String

Ancestors: S3

Yes
StorageClass

The class of storage used to store the select request results.

Type: String

Valid values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA

Ancestors: S3

No
Tagging

Container for tag information.

Type: Tag structure

Ancestors: S3

No
UserMetadata

Contains a list of metadata to store with the select restore results.

Type: MetadataEntry structure

Ancestors: S3

No

The Grantee container element (inside AccessControlList) contains the following elements.

Name Description Required
DisplayName

The screen name of the grantee.

Type: String

Ancestors: Grantee

No
EmailAddress

The email address of the grantee.

Type: String

Ancestors: Grantee

No
ID

The canonical user ID of the grantee.

Type: String

Ancestors: Grantee

No
Type

The type of the grantee.

Type: String

Ancestors: Grantee

No
URI

The URI of the grantee group.

Type: String

Ancestors: Grantee

No
Permission

Granted permission.

Type: String

Ancestors: Grantee

No

The Encryption container element (inside S3) contains the following elements.

Name Description Required
EncryptionType

The server-side encryption algorithm used when storing job results. The default is no encryption.

Type: String

Valid Values aws:kms | AES256

Ancestors: Encryption

No
KMSContext

Optional. If the encryption type is aws:kms, you can use this value to specify the encryption context for the select restore results.

Type: String

Ancestors: Encryption

No
KMSKeyId

The AWS Key Management Service (AWS KMS) key ID to use for object encryption.

Type: String

Ancestors: Encryption

No

The TagSet container element (inside Tagging) contains the following elements.

Name Description Required
Tag

Contains tags.

Type: Container

Ancestors: TagSet

No

The Tag container element (inside TagSet) contains the following elements.

Name Description Required
Key

Name of the tag.

Type: String

Ancestors: Tag

No
Value

Value of the tag.

Type: String

Ancestors: Tag

No

The MetadataEntry container element (inside UserMetadata) contains the following key-value pair elements to store with an object.

Name Description Required
MetadataKey

The metadata key.

Type: String

Ancestors:

No
MetadataEntry

The metadata value.

Type: String

Ancestors:

No

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. (This error does not apply to SELECT type requests.) 409 Conflict Client
GlacierExpeditedRetrievalNotAvailable Glacier expedited retrievals are currently not available. 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 Two 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 two 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, and only updates the restored copy's expiry time.

Query an Archive with a SELECT Request

The following is an example select restore request.

Copy
POST /object-one.csv?restore HTTP/1.1 Host: examplebucket.s3.amazonaws.com Date: Date: Sat, 20 Oct 2012 23:54:05 GMT Authorization: authorization string Content-Length: content length <RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Type>SELECT</Type> <Tier>Expedited</Tier> <Description>this is a description</Description> <SelectParameters> <InputSerialization> <CSV> <FileHeaderInfo>IGNORE</FileHeaderInfo> <Comments>#</Comments> <QuoteEscapeCharacter>"</QuoteEscapeCharacter> <RecordDelimiter>\n</RecordDelimiter> <FieldDelimiter>,</FieldDelimiter> <QuoteCharacter>"</QuoteCharacter> </CSV> </InputSerialization> <ExpressionType>SQL</ExpressionType> <Expression>select * from object</Expression> <OutputSerialization> <CSV> <QuoteFields>ALWAYS</QuoteFields> <QuoteEscapeCharacter>"</QuoteEscapeCharacter> <RecordDelimiter>\n</RecordDelimiter> <FieldDelimiter>\t</FieldDelimiter> <QuoteCharacter>\'</QuoteCharacter> </CSV> </OutputSerialization> </SelectParameters> <OutputLocation> <S3> <BucketName>example-output-bucket</BucketName> <Prefix>test-s3</Prefix> <AccessControlList> <Grant> <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"> <EmailAddress>jane-doe@example.com</EmailAddress> </Grantee> <Permission>FULL_CONTROL</Permission> </Grant> </AccessControlList> <UserMetadata> <MetadataEntry> <Name>test</Name> <Value>test-value</Value> </MetadataEntry> <MetadataEntry> <Name>other</Name> <Value>something else</Value> </MetadataEntry> </UserMetadata> <StorageClass>STANDARD</StorageClass> </S3> </OutputLocation> </RestoreRequest>

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 x-amz-restore-output-path: js-test-s3/qE8nk5M0XIj-LuZE2HXNw6empQm3znLkHlMWInRYPS-Orl2W0uj6LyYm-neTvm1-btz3wbBxfMhPykd3jkl-lvZE7w42/ Date: Sat, 20 Oct 2012 23:54:05 GMT Content-Length: 0 Server: AmazonS3

More Info