| « PreviousNext » | |
  | Did this page help you? Yes | No | Tell us about it... |
GET Object
Description
This implementation of the GET operation retrieves objects from Amazon S3. To
use GET, you must have READ access to the object. If you grant
READ access to the anonymous user, you can return the object without
using an authorization header.
An Amazon S3 bucket has no directory hierarchy such as you would find in a typical
computer file system. You can, however, create a logical hierarchy by using object key
names that imply a folder structure. For example, instead of naming an object
sample.jpg , you can name it
photos/2006/February/sample.jpg.
To get an object from such a logical hierarchy, specify the full key name for the
object in the GET operation. For a virtual hosted-style request example, if you have the
object photos/2006/February/sample.jpg, specify the resource as
/photos/2006/February/sample.jpg. For a path-style request example, if
you have the object photos/2006/February/sample.jpg in the bucket named
examplebucket, specify the resource as
/examplebucket/photos/2006/February/sample.jpg. For more information
about request types, see HTTP Host Header Bucket Specification in the Amazon Simple
Storage Service Developer Guide.
To distribute large files to many people, you can save bandwidth costs using BitTorrent. For more information, see Amazon S3 Torrent in the Amazon Simple Storage Service Developer Guide. For more information about returning the ACL of an object, see GET Object acl.
If the object you are retrieving is a GLACIER storage class object, the object is archived
in Amazon Glacier. You must first restore a copy using the POST Object restore API before
you can retrieve the object. Otherwise, this operation returns
InvalidObjectStateError error. For information about archiving objects
in Amazon Glacier, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer
Guide.
Versioning
By default, the GET operation returns the latest version of an object.
To return a different version, use the versionId subresource.
Note
If the latest version of the object is a Delete Marker, Amazon S3 behaves as if the object
was deleted and includes x-amz-delete-marker: true in the
response.
For more information about versioning, see PUT Bucket versioning. To see sample requests that use versioning, see Sample Request Getting a Specified Version of an Object.
Requests
Syntax
GET /ObjectNameHTTP/1.1 Host:BucketName.s3.amazonaws.com Date:dateAuthorization:signatureValueRange:bytes=byte_range
Request Parameters
There are times when you want to override certain response header values in a GET response.
For example, you might override the Content-Disposition response header
value in your GET request.
You can override values for a set of response headers using the query parameters listed in
the following table. These response header values are only sent on a successful
request, that is, when status code 200 OK is returned. The set of
headers you can override using these parameters is a subset of the headers that
Amazon S3 accepts when you create an object. The response headers that you can
override for the GET response are Content-Type,
Content-Language, Expires, Cache-Control,
Content-Disposition, and Content-Encoding. To override
these header values in the GET response, you use the request parameters described in
the following table.
Note
You must sign the request, either using an Authorization header or a Pre-signed URL, when
using these parameters. They can not be used with an unsigned (anonymous)
request.
| Parameter | Description | Required |
|---|---|---|
response-content-type |
Sets the Type: String Default: None | No |
response-content-language |
Sets the Type: String Default: None | No |
response-expires |
Sets the Type: String Default: None | No |
response-cache-control |
Sets the Type: String Default: None | No |
response-content-disposition |
Sets the Type: String Default: None | No |
response-content-encoding |
Sets the Type: String Default: None | No |
Request Headers
This implementation of the operation can use the following request headers in addition to the request headers common to all operations. For more information, see Common Request Headers.
| Name | Description | Required |
|---|---|---|
Range
|
Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35. Type: String Default: None Constraints: None | No |
If-Modified-Since
|
Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified). Type: String Default: None Constraints: None | No |
If-Unmodified-Since
|
Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed). Type: String Default: None Constraints: None | No |
If-Match
|
Return the object only if its entity tag ( Type: String Default: None Constraints: None | No |
If-None-Match
|
Return the object only if its entity tag ( Type: String Default: None Constraints: None | No |
Request Elements
This implementation of the operation does not use request elements.
Responses
Response Headers
| Header | Description |
|---|---|
x-amz-delete-marker |
Specifies whether the object retrieved was ( Type: Boolean Valid Values: Default: |
x-amz-expiration
|
If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the
Type: String |
x-amz-server-side-encryption
|
If the object is stored using server-side encryption, response includes this header with value of the encryption algorithm used. Type: String Valid Values: |
x-amz-restore |
Provides information about object restoration operation and expiration time of the restored object copy. For more information about archiving objects and restoring them, go to Object Lifecycle Management in Amazon Simple Storage Service Developer Guide Type: String Default: None |
x-amz-version-id |
Returns the version ID of the retrieved object if it has a unique version ID. Type: String Default: None |
x-amz-website-redirect-location |
When a bucket is configured as a website, you can set this metadata on the object so the website endpoint will evaluate the request for the object as a 301 redirect to another object in the same bucket or an external URL. Type: String Default: None |
Response Elements
This implementation of the operation does not return response elements.
Special Errors
This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.
Examples
Sample Request
The following request returns the object, my-image.jpg.
GET /my-image.jpg HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=
Sample Response
HTTP/1.1 200 OK x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran x-amz-request-id: 318BC8BC148832E5 Date: Wed, 28 Oct 2009 22:32:00 GMT Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT ETag: "fba9dede5f27731c9771645a39863328" Content-Length: 434234 Content-Type: text/plain Connection: close Server: AmazonS3 [434234 bytes of object data]
If the object had expiration set using lifecycle configuration, you get the following response with the x-amz-expiration header.
HTTP/1.1 200 OK x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran x-amz-request-id: 318BC8BC148832E5 Date: Wed, 28 Oct 2009 22:32:00 GMT Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="picture-deletion-rule" ETag: "fba9dede5f27731c9771645a39863328" Content-Length: 434234 Content-Type: text/plain Connection: close Server: AmazonS3 [434234 bytes of object data]
Sample response if object is archived in Amazon Glacier
An object archived in Amazon Glacier must first be restored before you can access it. If you attempt to access a Glacier object without restoring it, Amazon S3 returns the following error.
HTTP/1.1 403 Forbidden
x-amz-request-id: CD4BD8A1310A11B3
x-amz-id-2: m9RDbQU0+RRBTjOUN1ChQ1eqMUnr9dv8b+KP6I2gHfRJZSTSrMCoRP8RtPRzX9mb
Content-Type: application/xml
Date: Mon, 12 Nov 2012 23:53:21 GMT
Server: AmazonS3
Content-Length: 231
<Error>
<Code>InvalidObjectState</Code>
<Message>The operation is not valid for the object's storage class</Message>
<RequestId>9FEFFF118E15B86F</RequestId>
<HostId>WVQ5kzhiT+oiUfDCOiOYv8W4Tk9eNcxWi/MK+hTS/av34Xy4rBU3zsavf0aaaaa</HostId>
</Error>Sample Response if Latest Object is a Delete Marker
HTTP/1.1 404 Not Found x-amz-request-id: 318BC8BC148832E5 x-amz-id-2: eftixk72aD6Ap51Tnqzj7UDNEHGran x-amz-version-id: 3GL4kqtJlcpXroDTDm3vjVBH40Nr8X8g x-amz-delete-marker: true Date: Wed, 28 Oct 2009 22:32:00 GMT Content-Type: text/plain Connection: close Server: AmazonS3
Notice that the delete marker returns a 404 Not Found error.
Sample Request Getting a Specified Version of an Object
The following request returns the specified version of an object.
GET /myObject?versionId=3/L4kqtJlcpXroDTDmpUMLUo HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=Sample Response to a Versioned Object GET Request
HTTP/1.1 200 OK x-amz-id-2: eftixk72aD6Ap54OpIszj7UDNEHGran x-amz-request-id: 318BC8BC148832E5 Date: Wed, 28 Oct 2009 22:32:00 GMT Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3QBpUMLUo ETag: "fba9dede5f27731c9771645a39863328" Content-Length: 434234 Content-Type: text/plain Connection: close Server: AmazonS3 [434234 bytes of object data]
Sample Request with Parameters Altering Response Header Values
The following request specifies all the query string parameters in a GET request overriding the response header values.
GET /Junk3.txt?response-cache-control=No-cache&response-content-disposition=attachment%3B%20filename%3Dtesting.txt&response-content-encoding=x-gzip&response-content-language=mi%2C%20en&response-expires=Thu%2C%2001%20Dec%201994%2016:00:00%20GMT HTTP/1.1 x-amz-date: Sun, 19 Dec 2010 01:53:44 GMT Accept: */* Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=
Sample Response with Overridden Response Header Values
In the following sample response note the header values are set to the values specified in
the true request.
HTTP/1.1 200 OK x-amz-id-2: SIidWAK3hK+Il3/Qqiu1ZKEuegzLAAspwsgwnwygb9GgFseeFHL5CII8NXSrfWW2 x-amz-request-id: 881B1CBD9DF17WA1 Date: Sun, 19 Dec 2010 01:54:01 GMT x-amz-meta-param1: value 1 x-amz-meta-param2: value 2 Cache-Control: No-cache Content-Language: mi, en Expires: Thu, 01 Dec 1994 16:00:00 GMT Content-Disposition: attachment; filename=testing.txt Content-Encoding: x-gzip Last-Modified: Fri, 17 Dec 2010 18:10:41 GMT ETag: "0332bee1a7bf845f176c5c0d1ae7cf07" Accept-Ranges: bytes Content-Type: text/plain Content-Length: 22 Server: AmazonS3 [object data not shown]
Sample Request with the Range Header
The following request specifies the HTTP Range header to retrieve first 10 bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
GET /example-object HTTP/1.1 Host: example-bucket.s3.amazonaws.com x-amz-date: Fri, 28 Jan 2011 21:32:02 GMT Range: bytes=0-9 Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o= Sample Response with Specified Range of the Object Bytes
Sample Response
In the following sample response note the header values are set to the values specified in
the true request.
HTTP/1.1 206 Partial Content x-amz-id-2: MzRISOwyjmnupCzjI1WC06l5TTAzm7/JypPGXLh0OVFGcJaaO3KW/hRAqKOpIEEp x-amz-request-id: 47622117804B3E11 Date: Fri, 28 Jan 2011 21:32:09 GMT x-amz-meta-title: the title Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f" Accept-Ranges: bytes Content-Range: bytes 0-9/443 Content-Type: text/plain Content-Length: 10 Server: AmazonS3 [10 bytes of object data]
