Retrieving an object

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to retrieve an object has either of these formats:

  • With the bucket name included in the hostname:
    GET /object-name[?versionId=version-id] HTTP/1.1
  • With the bucket name following the hostname:
    GET /bucket-name/object-name/object-name[?versionId=version-id] HTTP/1.1

Required headers

The next list describes the headers you can use in a request to retrieve an object.

Authorization
Specifies user credentials or requests anonymous access.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.
Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the Date header above.

Optional request headers

If-Match
Specifies one or more values for comparison with the ETag of the specified object or object version. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag does not match any of the specified values, HCP returns a 412 (Precondition Failed) status code.
To specify the values for this header, use this format:
"value"[, "value"]...
In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").
Alternatively, you can specify a single asterisk (*) as the value for the If-Match header. All ETags match an asterisk in an If-Match header.
If-Modified-Since
Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 304 (Not Modified) status code.
To specify the date and time for this header, use one of these formats:
  • DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    For example: Tue, 07 Feb 2017 14:27:05 +0000

  • DDDD, dd-MMM-yyyy HH:mm:ss (+0000|GMT)

    For example: Tuesday, 07-Feb-17 14:27:05 +0000

  • DDD MMM d HH:mm:ss yyyy

    For example: Tue Feb 7 14:27:05 2017

If the value specified by the If-Modified-Since header doesn’t conform to one of the formats shown above, the header is ignored.
If-None-Match
Specifies one or more values for comparison with the ETag of the specified object or object version. If the ETag doesn’t match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 304 (Not Modified) status code.
To specify the values for this header, use this format:
"value"[, "value"]...
In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").
Alternatively, you can specify a single asterisk (*) as the value for the If-None-Match header. No ETags match an asterisk in an If-None-Match header.
If-Unmodified-Since
Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code.
For valid values for this header, see the description of the If-Modified-Since header above.
Range
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 list below shows the valid values for byte-range.
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.
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.
–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.
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.

Response headers

The next list describes the headers returned in response to a successful request to retrieve an object.

Accept-Ranges
Indicates that HCP can accept requests for part of the object data, specified as a range of bytes. The value of this header is always bytes.
Content-Length
Specifies the size, in bytes, of the returned data.
Content-Range
Specifies the range of bytes retrieved out of the total size of the object data. This header is returned only if the request headers include Range.
Content-Type
Specifies the Internet media type of the object or object version. This is one of, in order of precedence:
  • The Internet media type specified by the response-content-type request parameter.
  • The Internet media type specified in the Content-Type header when the object was stored.
  • An Internet media type determined by HCP based on the object name.
  • application/octet-stream if HCP cannot determine the Internet media type.
Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT
ETag
Specifies the ETag for the object.
ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.
Last-Modified
Specifies the date and time when the object or object version was last modified, in Greenwich Mean Time (GMT).
The date and time are expressed in this format:
DDD, dd MMM yyyy HH:mm:ss GMT
For example:
Tue, 17 Feb 2017 19:46:03 GMT
Modifying an object means modifying its metadata. You cannot modify the content of an object.
x-amz-meta-
For objects and object versions only, specifies a custom metadata property/value pair. The response headers include one x-amz-meta- header for each applicable pair.
x-amz-missing-meta
For objects and object versions only, indicates that the .metapairs annotation for the object or object version does not contain valid XML, that the first line in the annotation does not begin with the metapairs element. This header is returned only when applicable. The value is always 1 (one).
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.
x-hcp-labelretentionhold
Specifies whether the object is on labeled hold. Either true or false is returned.

For a user without privileged data access permission, the response header returns true or false indicating whether there are one or more labeled holds.

For a user with privileged data access permission:

  • If the response header returns true, an additional header, x-hcp-labelretentionhold-labels, is returned.
  • If the response header returns false, the x-hcp-labelretentionhold-labels header is not returned.
x-hcp-labelretentionhold-labels
If the object is on labeled hold (x-hcp-labelretentionhold:true) and the user has privileged data access and read permission on the bucket, this header is returned with a JSON format string specifying all labeled holds.

Example

x-hcp-labelretentionhold-labels: [{"id":"UniqueLabelHold-1","hold": true},
[{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]
x-amz-object-lock-mode
Specify the Object Lock mode status for an object. The value can be either GOVERNANCE or COMPLIANCE.
GOVERNANCE
Use for objects that are subject to retention policies that are governed by a regulatory body.
COMPLIANCE
Use for objects that are subject to strict regulatory requirements.
Example
x-amz-object-lock-mode: GOVERNANCE
x-amz-object-lock-retain-until-date
Specify the date and time until which an object must be retained. The date and time must be in YYYY-MM-DDTHH:MM:SSZ format, where YYYY represents the year, MM represents the month, DD represents the day, T represents the time separator, HH represents the hour in 24-hour format, MM represents the minute, SS represents the second and Z represents the time zone.
Example
x-amz-object-lock-retain-until-date: 2023-03-30T00:00:00Z
x-amz-object-lock-legal-hold
Specify the Legal hold status of an object version. Valid values are ON and OFF.
ON
You cannot overwrite or delete the object version until you remove the legal hold status.
OFF
You can overwrite or delete the object version.
Example
s3curl.pl --id=hds -- -k -v "https://domainname.com/n1/test3.txt?legal-hold" -X PUT -d "<LegalHold><Status>ON</Status></LegalHold>
x-hcp-retention
Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.
x-hcp-retentionhold
Specifies whether the object is on hold. Either true or false is returned.

Status codes

The next table describes HTTP status codes that can be returned in response to a request to retrieve an object.

Code Meaning Description
200 OK

HCP successfully processed the request.

Note: If the number of bytes returned does not equal the value of the Content-Length response header, try the request again later.

204 No Content

One of these:

  • The current version of the specified object is a delete marker or a delete record.
  • The request did not specify a version ID or specified an invalid version ID.
  • The object does not exist.
206 Partial Content HCP successfully retrieved the data in the byte range specified by the Range header.
304 Not Modified

One of these:

  • The request included an If-None-Match header, and the ETag for the specified object or object version matched a value specified by the header.
  • The request included an If-Modified-Since header, and the specified object or object version was not modified after the date and time specified by the header.
403 Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have read permission for the specified bucket or object.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The object exists, but the HCP system does not have the object data. Retry the request, targeting a different system in the replication topology.
  • The object is in the process of being deleted.
404 Not Found

One of these:

  • The specified object or object version does not exist.
  • The current version of the specified object is a delete marker or delete record.
  • The specified item is a folder.
  • The specified bucket does not exist.
409 Conflict Possible reasons include that the object data is currently being written to HCP.
412 Precondition Failed

One of these:

  • The request included an If-Match header, and the ETag for the specified object or object version does not match any of the values specified by the header.
  • The request included an If-Unmodified-Since header, and the specified object or object version was modified after the date and time specified by the header.
416 Requested Range Not Satisfiable

The request included a Range header that specified either:

  • A range in which the starting value is greater than or equal to the size of the object data
  • An offset of zero
500 Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503 Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Retrieving an object

Here is a sample GET request that retrieves the current version of the object named mktg/campaign_GoGetEm_expenses.xls in the finance bucket. Versioning is enabled on the bucket. Because the user has data access permission on the bucket, labeled holds are returned in a JSON format string.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -v -k 
"https://finance.europe.hcp.example.com/mktg/campaign_GoGetEm_expenses.xls"

Request headers

GET /mktg/campaign_GoGetEm_expenses.xls HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 26 June 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:3ymfU6KeNWnFEvpphFxYvJ881W

Response headers

HTTP/1.1 200 OK
Date: Fri, 26 June 2020 17:19:26 GMT
ETag: "6ed7faad1e0661c03ad65a4317d4a94c"
Accept-Ranges: bytes
x-amz-version-id: 87288825190337
Last-Modified: Mon, 13 Feb 2017 17:44:53 GMT
Content-Type: application/vnd.ms-excel
X-HCP-Retention:  0
X-HCP-LabelRetentionHold: true
X-HCP-LabelRetentionHold-Labels: '[{"id":"UniqueLabelHold-1","hold":true}, 
{"id":"UniqueLabelHold-2","hold":true}, {"id":"UniqueLabelHold-3","hold":true}]'
Content-Length: 94328

Example: Conditionally retrieving an object

Here is a sample GET request that retrieves the current version of the object named mktg/campaign_GoGetEm_expenses.xls in the finance bucket only if the ETag for the object does not match a specified value. In this example, the specified value is the ETag of the first version of mktg/campaign_GoGetEm_expenses.xls. The request writes the object data to a file named mktg_GoGetEm.xls. The request is being made while versioning is enabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k
     "https://finance.europe.hcp.example.com/mktg/campaign_GoGetEm_expenses.xls"
     -H 'If-None-Match:"74d824cd5076a1361da128ee18e5a42b"' >
     mktg_GoGetEm.xls

Request headers

GET /mktg/campaign_GoGetEm_expenses.xls HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:3ymfU6KeNWnFEvpphFxYvJ881Wg=
If-None-Match: "74d824cd5076a1361da128ee18e5a42b"

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "6ed7faad1e0661c03ad65a4317d4a94c"
Accept-Ranges: bytes
x-amz-version-id: 87288825190337
Last-Modified: Mon, 13 Feb 2017 17:44:53 GMT
Content-Type: application/vnd.ms-excel
Content-Length: 94328

Example 2: Retrieving an old version of an object

Here is a sample GET request that retrieves an old version of the object named AcctgBestPractices.doc in the finance bucket. The request writes the object data to a file named AcctgBestPractices.doc-10-08-16.doc. The request is being made while versioning is enabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com/
     AcctgBestPractices.doc?versionId=87288808614529" >
     AcctgBestPractices-10-08-16.doc

Request headers

GET /AcctgBestPractices.doc?versionId=87288808614529 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:6Am3akZkcfc4fD3WXSBFr+dV7DE=

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "5ab7542f753b09fdb73141a66c134b9"
Accept-Ranges: bytes
x-amz-version-id: 87288808614529
Last-Modified: Wed, 28 Dec 2016 21:06:52 GMT
Content-Type: application/msword
Content-Length: 3557448

Example: Retrieving part of an object

Here is a sample GET request that retrieves the first hundred thousand bytes of the object named quarterly_rpts/Q4_2019.ppt in the finance bucket. The request writes the object data to a file named Q4_2019_Rpt_Part-1. The request is being made while versioning is disabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k
     "https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt"
     -H "Range: bytes=0-99999" > Q4_2019_Rpt_Part-1

Request headers

GET /quarterly_rpts/Q4_2019.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:f6RKgLahMlrfc7de89aJ0Xt8wKM=
Range: bytes=0-99999

Response headers

HTTP/1.1 206 Partial Content
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "617e8ef649d40cda1f7f3ca81c97a06a"
Accept-Ranges: bytes
Last-Modified: Fri, 20 Jan 2017 17:19:26 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Range: bytes 0-99999/235813
Content-Length: 100000