         | 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.
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.
Versioning
By default, the GET operation returns the latest version of an object.
To return a different version, use the versionId subresource.
![[Note]](http://docs.amazonwebservices.com/docs-common/images/note.png) | Note |
|---|---|
If the latest version of the object is a Delete Marker, Amazon S3 behaves as if the object
was deleted and includes |
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 |
| 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-version-id |
Returns the version ID of the retrieved object if it has a unique version ID. 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 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]
