Retrieving an object

You use the HTTP GET method to retrieve an object from a bucket. Retrieving an object means retrieving the object data. To retrieve an object, you need read permission for the bucket containing the object or for the object itself.

Retrieving an object version

By default, a request to retrieve an object retrieves the current version of the object. However, while versioning is enabled for the target bucket, you can use the versionId query parameter to retrieve a specific version of an object.

Valid values for the versionId parameter are integers greater than or equal to zero. Normally, the value is the version ID of a version of the object specified in the request.

The versionId query parameter is not case sensitive.

If you include the versionId parameter in a GET request while versioning is disabled, the parameter is ignored.

For information about object versions, see Versioning.

Objects with custom metadata

If a retrieved object or object version has custom metadata, the headers returned in response to the request include the applicable x-amz-meta- headers. For information about x-amz-meta- headers, see Custom metadata.

Retrieving part of an object

You can use the Range header in a GET request to retrieve only part of an object or object version. By using the Range header, you can limit the amount of data returned, even when you don’t know the size of the object.

The value of the Range header is the range of bytes you want to retrieve. The first byte of the data for an object is in position 0 (zero), so a range of 1-5 specifies the second through sixth bytes, not the first through fifth.

To specify a byte range in a range header, you use this format:

Range: bytes=byte-range

The table below shows the valid values for byte-range.

Value Description Example
start-position–end-position

Bytes in start-position through end-position, inclusive. If end-position is greater than the size of the object data, HCP returns the bytes in start-position through the end of the data.

Valid values for start-position and end-position are integers greater than or equal to zero.

For the specified range to be valid, end-position must be greater than or equal to start-position.

Five hundred bytes beginning with the two-hundred-first:

bytes=200-699

start-position–

Bytes in start-position through the end of the object data.

Valid values for start-position are integers greater than or equal to zero.

All the bytes beginning with the seventy-sixth and continuing through the end of the object data:

bytes=75-

–offset-from-end

Bytes in the offset-from-end position, counted back from the last position in the object data, through the end of the object data. If offset-from-end is greater than the size of the object data, HCP returns the complete object data.

Valid values for offset-from-end are integers greater than or equal to zero.

The last 25 bytes of the object data:

-bytes=-25

These considerations apply to Range header values:

If you specify a valid range in which the start position is less than the size of the object data, HCP returns the requested range of data with a 206 (Partial Content) status code.

If you specify a valid range in which the start position is greater than or equal to the size of the object data, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.

If you specify an offset of zero, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.

If you specify an invalid value (for example, a value in which the start position is greater than the end position, HCP ignores the Range header and returns the complete object data with a status code of 200 (OK).

A GET request to retrieve a range of bytes in a multipart object is most efficient when the start and end bytes for the range are aligned with the start and end bytes for one or more of the parts uploaded to create the object.

You cannot retrieve a part of an in-progress multipart upload. For more information about multipart objects, see Working with multipart uploads.

Conditionally retrieving an object

You can choose to retrieve an object or object version only if its ETag and/or last modification date and time meet certain criteria. You might do this, for example, in an application that maintains a local cache of frequently used objects. With such an application, you can reduce the load on HCP and the network by retrieving objects only if they have changed since they were cached.

You use the If-Match, If-None-Match, If-Modified-Since, and If-Unmodified-Since request headers to make GET requests conditional:

The If-Match and If-None-Match headers compare the ETag for the requested object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.

The If-Modified-Since and If-Unmodified-Since headers compare the date and time the requested object or object version was last modified to a date and time that you specify.

If the requested object or object version meets all the conditions specified by the conditional headers included in the request, HCP returns the object data. If the requested object or object version does not meet the condition specified by:

An If-Match or If-Unmodified-Since header, HCP returns a 412 (Precondition Failed) status code and does not return the object data

An If-None-Match or If-Modified-Since header, HCP returns a 304 (Not Modified) status code and does not return the object data

If a request includes multiple different conditional headers, HCP processes any If-Match and If-None-Match headers before any If-Modified-Since or If-Unmodified-Since headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the rest.

Overriding response headers

In a request to retrieve an object or object version, you can specify values to be returned in certain response headers. The values you specify in the request override any values that might otherwise be returned for those headers. The headers you can override are returned only in response to a successful request.

To specify response header values, you can use the request headers listed in the table below. The valid values for each request header are the valid values for the corresponding response header.

Request header Response header
response-cache-control Cache-Control
response-content-disposition Content-Disposition
response-content-encoding Content-Encoding
response content-language Content-Language
response-content-type Content-Type
response-expires Expires

This book does not describe the response headers listed above, with the exception of Content-Type. For information about the other response headers, see http://www.w3.org/Protocols/rfc2616/rfc2616.html.

© 2015, 2020 Hitachi Vantara LLC. All rights reserved.