Working with objects
With the Hitachi API for Amazon S3, you can perform operations on individual objects.
Storing an object
You use the HTTP PUT method to store an object in a bucket. To store an object, you need write permission for the bucket.
For a request to store an object, the request body consists of the data in a specified file. This data becomes the object content.
When you store an object, you specify a name for it. The object name does not need to be the same as the name of the file containing the original data.
If versioning is enabled and you try to store an object with the same name as an existing object, HCP creates a new version of the object. If versioning is disabled and you try to store an object with the same name as an existing object, HCP returns a 409 (Conflict) status code and does not store the object.
You can add custom metadata to an object in the same request as you use to store the object. To do this, you use x-amz-meta-
headers.
You can specify an ACL for an object in the same request as you use to store the object. To do this, you use an ACL header. You cannot use an ACL request body when storing an object.
If the ACL you specify in a request to store an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not store the object.
If you are an authenticated user, when you store an object, you become the object owner. If you are accessing the bucket anonymously, the new object has no owner.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to store an object has either of these formats:
- With the bucket name included in the hostname:
PUT /object-name HTTP/1.1
- With the bucket name following the hostname:
PUT /bucket-name/object-name HTTP/1.1
The next list describes the headers you can use in a request to store an object.
Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the data being stored.
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
Content-MD5
Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.
When you store an object, you can use the
Content-MD5
request header to ensure the integrity of the object data. The value you specify for this header must be the Base64-encoded MD5 hash of the original file data.When you include the
Content-MD5
header in a request to store an object, HCP calculates the Base64-encoded MD5 hash of the data it receives and compares that to the header value. If the values don’t match, HCP returns a 400 (Bad Request) status code and does not store the object.Content-Type
Specifies the Internet media type of the data being stored. Valid values are Internet media types (for example,
text/plain
,application/xml
, orimage/jpeg
).Expect
Tells the application not to send the request body if the request headers are rejected. The only valid value is
100-continue
. This value is not case sensitive.You can use the
Expect
request header in a request to store an object to tell the application not to send the request body (the data) to HCP if the request headers are rejected. This prevents unnecessary network bandwidth usage.x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual
x-amz-grant-
headers to add the ACL, thex-amz-acl
header is invalid.x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-full-control
header is invalid.x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read
header is invalid.x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read-acp
header is invalid.x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write
header is invalid.x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write-acp
header is invalid.x-amz-meta-
Adds custom metadata to the object.
x-amz-server-side-encryption
Requests that the response headers include x-amz-server-side-encryption, which indicates whether objects stored in HCP are encrypted. The value of the
x-amz-server-side-encryption
request header can be any character string.When you store an object, you can use the
x-amz-server-side-encryption
request header to determine whether objects stored in HCP are encrypted. If stored objects are encrypted, the response headers includex-amz-server-side-encryption
with a value representing the encryption algorithm and key length HCP is using. If stored objects are not encrypted, the value of thex-amz-server-side-encryption
response header is None.x-hcp-labelretentionhold
Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold value pairs.
id
Unique label name. The maximum label size is 64 characters.
hold
Either
true
orfalse
.
Example
x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, {"id":"UniqueLabelHold-2","hold":true}]
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. This value can be either
true
orfalse
.
The next list describes the headers returned in response to a successful request to store an object.
Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always
0
(zero).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.
x-amz-server-side-encryption
Specifies whether objects stored in HCP are encrypted. Possible values are:
- If objects are encrypted,
AES256
- If objects are not encrypted,
None
This header is returned only if the request headers include
x-amz-server-side-encryption
.- If objects are encrypted,
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.
The next table describes HTTP status codes that can be returned in response to a request to store an object.
Code | Meaning | Description |
200 | OK |
Possible reasons include:
|
400 | Bad Request |
Possible reasons include:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
Possible reasons include:
|
409 | Conflict |
One of these:
|
411 | Length Required | Either the request does not include a Content-Length header, or the request includes a Content-Length header with no value. |
413 | Request Entity Too Large | The object you are trying to store is too big for the amount of remaining space in the bucket. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
501 | Not Implemented | The request includes the x-amz-acl header with an invalid value. |
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. |
Here is a sample PUT request that stores an object named quarterly_rpts/Q4_2019.ppt in the finance bucket. In this example, the retention value of the object is set to five days past the time when the object was stored.
The example also shows the response headers HCP returns while versioning is enabled for the bucket and while versioning is disabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --put=/quarterly_rpts/Q4_2019.ppt -- -k "https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt" -H "x-hcp-retention: A+5d"
Request headers
PUT /quarterly_rpts/Q4_2019.ppt HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 20 Jan 2017 17:19:26 +0000 Authorization: AWS bGdyZWVu:HbkRBWvyO3YQO55Bm0VS3RMatvg= Content-Length: 235813 x-hcp-retention: A+5d
Response headers with versioning enabled
HTTP/1.1 200 OK Date: Fri, 20 Jan 2017 17:19:26 GMT x-amz-version-id: 87288727469825 ETag: "617e8ef649d40cda1f7f3ca81c97a06a" Content-Length: 0
Response headers with versioning disabled
HTTP/1.1 200 OK Date: Fri, 20 Jan 2017 17:19:26 GMT ETag: "617e8ef649d40cda1f7f3ca81c97a06a" Content-Length: 0
Here is a sample PUT request that stores and places a labeled hold on an object named quarterly_rpts/Q4_2019.ppt in the finance bucket.
The user ID, lgreen, has privileged data access permission.
Request with s3curl command line
./s3curl.pl --id=lgreen --put=/quarterly_rpts/Q4_2019.ppt -- -v -k "https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt" -H 'x-hcp-labelretentionhold: [{"id":"UniqueLabelHold-1","hold":true}]'
Request headers
PUT /quarterly_rpts/Q4_2019.ppt HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri,12 Jun 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:HbkRBWvyO3YQO55Bm0VS3RMatvg= X-HCP-Retention: 0 X-HCP-RetentionHold: true X-HCP-LabelRetentionHold: true Content-Length: 235813
Response headers
HTTP/1.1 200 OK Date: Fri, 12 Jun 2020 17:19:26 GMT ETag: "617e8ef649d40cda1f7f3ca81c97a06a" Content-Length: 0
Here is a sample PUT request that stores an object named hum_res/budget_proposals/BudgProp-2020 in the finance bucket, for which versioning is disabled. The object is stored with custom metadata specified by three x-amz-meta- headers and a canned ACL specified by the x-amz-acl header.
Request with s3curl command line
./s3curl.pl --id=lgreen --put=/hum_res/budget_proposals/BudgProp-2020 -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020" -H "x-amz-meta-author: P.D. Grey" -H "x-amz-meta-author: Morgan White" -H "x-amz-meta-author: Paris Black" -H "x-amz-acl: authenticated-read"
Request headers
PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Wed, 16 Nov 2016 23:29:17 +0000 Authorization: AWS bGdyZWVu:FiWxioJHDGMLyP0WkCuqUpRqr2w= x-amz-meta-author: P .D. Grey x-amz-meta-author: Morgan White x-amz-meta-author: Paris Black x-amz-acl: authenticated-read Content-Length: 881932
Response headers
HTTP/1.1 200 OK Date: Wed, 16 Nov 2016 23:29:17 GMT ETag: "76216527ff2f6219f7c29251a619c8db" Content-Length: 0
Creating a folder
You use the HTTP PUT method to create a folder in a bucket. To create a folder, you need write permission for the bucket.
To tell HCP to create a folder instead of an object in response to a PUT request, you can do either these:
- Include a forward slash (/) or the percent-encoded equivalent (%2F) after the folder name in the request.
- Include the
Content-Type
header in the request with a value ofx-directory
.
In either case, you also need to include the Content-Length
header in the request. However, HCP ignores any request body.
When you create a folder, you specify a name for it. The rules for folder names are the same as the rules for object names.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to create a folder has either of these formats:
- With the bucket name included in the hostname:
PUT /folder-name[(/|%2F)] HTTP/1.1
- With the bucket name following the hostname:
PUT /bucket-name/folder-name[(/|%2F)] HTTP/1.1
The list below describes the headers you can use in a request to create a folder.
Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the data being stored. In a request to create a folder, the value of this header should be
0
(zero).Even if you specify a value greater than zero for this header, no request body is sent to HCP.
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
Content-Type
Specifies the Internet media type of the request body. The only valid value is
x-directory
.This header is ignored if the folder name in the request ends with a forward slash (/) or the percent-encoded equivalent (%2F). Otherwise, this header is required.
Transfer-Encoding
Specifies the encoding transformation for the request body. The only valid value is
chunked
.Even if you include this header in the request, no request body is sent to HCP.
The list below describes the headers returned in response to a successful request to create a folder.
Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always
0
(zero).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 folder.
Even though a folder has no content, HCP returns an ETag for it. However, because folders have no content, all folders have the same ETag.
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.
The table below describes HTTP status codes that can be returned in response to a request to create a folder.
Code | Meaning | Description |
200 | OK | HCP successfully created the folder. |
400 | Bad Request | Possible reasons include that the request does not include a Content-Length header. |
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | The specified bucket does not exist. |
409 | Conflict | An object or folder with the specified name already exists. |
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. |
Here’s a sample PUT request that creates a folder named budget_proposals in the r&d folder in the finance bucket. If the r&d folder doesn’t already exist, this request also creates that folder. The request is being made while versioning is enabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --put ~ -- -k "https://finance.europe.hcp.example.com/r&d/budget_proposals%2F" -H "Content-Length:0"
Request headers
PUT /r&d/budget_proposals%2F HTTP/1.1 Host: finance.europe.hcp.example.com Transfer-Encoding: chunked Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:VsSmWFRWwTPWPjH+QEs6Z2Qwf84= Content-Length: 0
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT x-amz-version-id: 87395113368065 ETag: "d41d8cd98f00b204e9800998ecf8427e" Content-Length: 0
Checking the existence of an object or folder
You use the HTTP HEAD method to check the existence of an object or folder in a bucket. To check the existence of an object, you need read permission for the bucket containing the object or for the object itself. To check the existence of a folder, you need read permission for the bucket.
In response to a request to check the existence of an object or folder, HCP returns a 200 (OK) status code if the object or folder exists and a 404 (Not Found) status code if the object or folder does not exist. If you do not have read permission for the bucket or object, HCP returns a 403 (Forbidden) status code.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to check the existence of an object, object version, or folder has either of these formats:
- With the bucket name included in the hostname:
HEAD /(object-name[?versionId=version-id])|(folder-name(/|%2F)) HTTP/1.1
- With the bucket name following the hostname:
HEAD /bucket-name/(object-name[?versionId=version-id])|(folder-name(/|%2F)) HTTP/1.1
The next list describes the required headers to use in a request to check the existence of an object, object version, or folder.
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
If-Match
Specifies one or more values for comparison with the ETag of the specified item. 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 anIf-Match
header.If-Modified-Since
Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified item 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 does not conform to one of the formats shown above, the header is ignored.- DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
If-None-Match
Specifies one or more values for comparison with the ETag of the specified item. If the ETag does not 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 anIf-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 item 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, see the description of the
If-Modified-Since
header above.
The next list describes the headers returned in response to a successful request to check the existence an object, object version, or folder.
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 object, object version, or folder. For a delete marker, this is the size of the object or object version that was deleted.
Content-Type
Specifies the Internet media type of the object or object version, or folder. 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. For a folder, the value of theContent-Type
header is alwaysapplication/octet-stream
.
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 specified object, object version, or folder. For a delete marker, this is the ETag of the object or object version that was deleted.
Last-Modified
Specifies the date and time when the object, object version, or folder was last modified, in Greenwich Mean Time (GMT). For a delete marker, this is the date and time when the delete marker was created.
The date and time are expressed in this format:
DDD, dd MMM yyyy HH:mm:ss GMT
For example:
Tue, 07 Feb 2017 19:46:03 GMT
Modifying an object means modifying its metadata. You cannot modify the content of an object.
x-amz-delete-marker
For requests that specify a version ID, indicates whether the version ID identifies a delete marker. This header is returned only for delete markers and only if versioning is enabled for the bucket. The value is always
true
.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 themetapairs
element, or that the specified version ID identifies a delete marker and the deleted object version had an annotation. This header is returned only when applicable. The value is always1
(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. A Boolean value of
true
orfalse
is returned.For a user without privileged data access permission, the response header returns
true
orfalse
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
, thex-hcp-labelretentionhold-labels
header is not returned
- If the response header returns
x-hcp-labelretentionhold-labels
If the object is on labeled hold (
x-hcp-labelretentionhold:true
) and the user has privileged data access and read permissions 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-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. A Boolean value of
true
orfalse
is returned.
The following table describes HTTP status codes that can be returned in response to a request to check the existence of an object, object version, or folder.
Code | Meaning | Description |
200 | OK | Possible reasons include:
|
304 | Not Modified |
One of these:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
409 | Conflict | Possible reason includes that the object data is currently being written to HCP. |
412 | Precondition Failed |
One of these:
|
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. |
Here is a sample HEAD request that checks the existence of an object named sales_quotas_2020.pdf in the finance bucket. Versioning is disabled 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 --head -- -k "https://finance.europe.hcp.example.com/sales_quotas_2020.pdf"
Request headers
HEAD /sales_quotas_2020.pdf HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 18 September 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:LDa147ALd+O5Q02LjkGRrXwSGAc=
Response headers
HTTP/1.1 200 OK Date: Fri, 18 September 2020 17:19:26 GMT ETag: "62e82b6d3ef16070a8d75ab55c42b80d" Accept-Ranges: bytes Last-Modified: Fri, 03 Jan 2020 14:28:48 GMT Content-Type: application/pdf 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: 23166
Here is a sample HEAD request that checks the existence of a version of the object named AcctgBestPractices.doc, which has custom metadata. The request is being made while versioning is enabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --head -- -k "https://finance.europe.hcp.example.com/AcctgBestPractices.doc ?versionId=87288758401473"
Request headers
HEAD /AcctgBestPractices.doc?versionId=87288815588289 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:EUa2evHNUtlw8Xu/1iFdGgWSDc8=
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT ETag: "26aa5129552e57fc64e10aa5b3911ee2" Accept-Ranges: bytes x-amz-version-id: 87288758401473 Last-Modified: Sun, 29 May 2016 14:56:05 GMT x-amz-meta-author: P.D. Grey,Morgan White,Paris Black Content-Type: application/msword Content-Length: 3206178
Here is a sample HEAD request that checks whether the object named AcctgBestPractices.doc has been modified since December 20, 2016, at 23:59:59 GMT. The request is being made while versioning is enabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --head -- -k "https://finance.europe.hcp.example.com/AcctgBestPractices.doc" -H "If-Modified-Since: Tue, 20 Dec 2016 23:59:59 +0000"
Request headers
HEAD /AcctgBestPractices.doc HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:Yn7gcia/yqzGRKRC04HaOuD3aH0= If-Modified-Since: Tue, 20 Dec 2016 23:59:59 +0000
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT ETag: "764f38262c6e581f678e1ac9b0211ae8" Accept-Ranges: bytes x-amz-version-id: 87288815588289 Last-Modified: Thu, 29 Dec 2016 19:42:16 GMT x-amz-meta-author: Morgan White Content-Type: application/msword Content-Length: 3552369
Here is a sample HEAD request that checks the existence of a folder named r&d/budget_proposals in the finance bucket. The request is being made while versioning is enabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --head -- -k "https://finance.europe.hcp.example.com/r&d/budget_proposals/"
Request headers
HEAD /r&d/budget_proposals/ HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:4u9bhK0DQF2FLZtT0VVwMKdvm+I=
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT ETag: "d41d8cd98f00b204e9800998ecf8427e" Accept-Ranges: bytes x-amz-version-id: 87395113368065 Last-Modified: Wed, 18 Jan 2017 14:40:26 GMT Content-Type: application/octet-stream Content-Length: 0
Adding an ACL to an object
You use the HTTP PUT method with the acl query parameter to add an ACL to an existing object. Adding an ACL to an object replaces any existing ACL in its entirety. You cannot modify an existing ACL in place.
To add an ACL to an object, you need write ACL permission for the bucket containing the object or for the object itself.
You can add an ACL only to the current version of an object. However, the ACL you add applies to all versions of the object.
To add an ACL to an object, you can use either request headers or an ACL request body. You cannot use ACL headers and an ACL request body in the same request.
With ACL headers, you can specify either a canned ACL or individual x-amz-grant-
headers. You cannot specify both a canned ACL and an x-amz-grant-
header in the same request.
You can use an ACL request body to change the owner of an object. You cannot use ACL headers to do this. To change the owner of an object, you need both write ACL permission for the bucket or object and change owner permission for the bucket.
If you try to add an ACL that specifies a user account that does not exist, HCP returns a 400 (Bad Request) status code and does not add the ACL to the object.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to add an ACL to an object has either of these formats:
- With the bucket name included in the hostname:
PUT /object-name?acl HTTP/1.1
- With the bucket name following the hostname:
PUT /bucket-name/object-name?acl HTTP/1.1
The acl query parameter is not case sensitive.
The list below describes the headers you can use in a request to add an ACL to 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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
Content-Length
Specifies the size, in bytes, of the request body.
This header is required when you’re using an ACL request body to add an ACL to an object. If you’re using ACL headers to add the ACL, the
Content-Length
header is invalid.Content-Type
Specifies the Internet media type of the request body. This header is valid only when the ACL is specified in the request body. The only valid values are
application/xml
andtext/xml
.x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual
x-amz-grant-
headers to add the ACL, thex-amz-acl
header is invalid.x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-full-control
header is invalid.x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read
header is invalid.x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read-acp
header is invalid.x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write
header is invalid.x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write-acp
header is invalid.
The list below describes the headers returned in response to a successful request to add an ACL to an object.
Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to add an ACL to an object, the value of this header is always
0
(zero).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
The table below describes HTTP status codes that can be returned in response to a request to add an ACL to an object.
Code | Meaning | Description |
200 | OK | HCP successfully added the ACL to the object. |
400 | Bad Request |
Possible reasons include:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
409 | Conflict | Possible reasons include that the object data is currently being written to HCP. |
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. |
Here’s a sample PUT request that adds a canned ACL to the object named AcctgBestPractices.doc. The ACL grants read permission to all users.
Request with s3curl command line
./s3curl.pl --id=lgreen --put ~ -- -k "https:// finance.europe.hcp.example.com/AcctgBestPractices.doc?acl" -H "x-amz-acl: public-read"
Request headers
PUT /AcctgBestPractices.doc?acl HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:C8KpGuK62B7j2US0kN0Bl0Wx48k= x-amz-acl: public-read
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Length: 0
Here’s a sample PUT request that uses an ACL request body to add an ACL to the object named mktg/budget_proposals/BudgProp-2020. The ACL grants read access to all authenticated users and full control user pblack. It makes no change to the object owner. The ACL request body is in a file named acl-3.xml.
Request body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AccessControlList>
<Grant>
<Grantee xsi:type="Group"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
</Grantee>
<Permission>READ</Permission>
</Grant>
<Grant>
<Grantee xsi:type="CanonicalUser"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ID>b9d39144-a081-4761-b0e8-b8fb51e10192</ID>
<DisplayName>pblack</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>
Request with s3curl command line
./s3curl.pl --id=lgreen --put=acl-3.xml -- -k "https://finance.europe.hcp.example.com/mktg/budget_proposals/ BudgProp-2020?acl"
Request headers
PUT /mktg/budget_proposals/BudgProp-2020?acl HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:mRqVstjwWxvfEFr8JajjrPcd8eY= Content-Length: 632
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Length: 0
Retrieving the ACL for an object
You use the HTTP GET method with the acl query parameter to retrieve the ACL for an object. To retrieve the ACL for an object, you need read ACL permission for the bucket containing the object or for the object itself.
The object ACL is returned in an XML response body. The format of the response body is the same as the format you use for the ACL request body when you add an ACL to a bucket.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to retrieve an object ACL has either of these formats:
- With the bucket name included in the hostname:
GET /object-name?acl HTTP/1.1
- With the bucket name following the hostname:
GET /bucket-name/object-name?acl HTTP/1.1
The acl query parameter is not case sensitive.
The list below describes the headers you can use in a request to add an ACL to 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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
x-hcp-pretty-print
Optionally, requests that the XML response body be formatted for readability. Valid values are:
true
Format the XML response body for readability.
false
Do not apply any special formatting to the XML response body.
The default is false.
The values
true
andfalse
are not case sensitive.
The list below describes the headers returned in response to a successful request to retrieve an object ACL.
Content-Type
Specifies the Internet media type of the response body. For a request to retrieve an object ACL, the value of this header is always
application/xml;charset=UTF-8
.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
Transfer-Encoding
Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always
chunked
.
The table below describes HTTP status codes that can be returned in response to a request to retrieve an object ACL.
Code | Meaning | Description |
200 | OK | HCP successfully retrieved the object ACL. |
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
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. |
Here’s a sample GET request that retrieves the ACL for the object named mktg/budget_proposals/BudgProp-2020.
Request with s3curl command line
./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com/mktg/budget_proposals/ BudgProp-2020?acl" -H "x-hcp-pretty-print: true"
Request headers
GET /mktg/budget_proposals/BudgProp-2020?acl HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:3pB7HQ8LNIHaFzHToefVgDD9hVo= x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
<DisplayName>lgreen</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
<DisplayName>lgreen</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xsi:type="Group"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI>
</Grantee>
<Permission>READ</Permission>
</Grant>
<Grant>
<Grantee xsi:type="CanonicalUser"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ID>b9d39144-a081-4761-b0e8-b8fb51e10192</ID>
<DisplayName>pblack</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>
Copying an object
You use the HTTP PUT method with the x-amz-copy-source
header to copy an object from one location to another. The source and target locations can be two different buckets within the same tenant, or they can be the same bucket. You can specify a name for the target object that is different from the name of the source object.
To copy an object, you need read permission for the bucket containing the source object or for the source object itself, and write permission for the target bucket.
By default, a copy operation copies the current version of the source object specified in the request. If versioning is enabled for the source bucket, you can use the versionId query parameter with the source object specification to copy a specific version of the object.
- If the version identified by the versionId parameter is a delete marker, HCP returns a 503 (Service Unavailable) status code.
- If the current version of the source object is a delete marker and you do not specify a version ID, HCP returns a 404 (Not Found) status code.
HCP does not copy version IDs with objects. The object created by a copy operation has its own version ID.
HCP also does not copy ACLs with objects. However, in the copy request, you can specify an ACL for the target object. To do this, you need to use ACL headers. You cannot use an ACL request body when copying an object. If the ACL you specify in a request to copy an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not copy the object.
By default, HCP copies any custom metadata for the source object to the target object. However, in the copy request, you can specify replacement custom metadata to be used for the target object. To apply this custom metadata to the target object, you need to include the x-amz-metadata-directive
header with a value of REPLACE
in the copy request.
If you are an authenticated user, when you copy an object, you become the owner of the target object. If you are accessing the bucket anonymously, the target object has no owner.
In response to a request to copy an object, HCP returns an XML response body containing the ETag and last modification date of the target object.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to copy an object has either of these formats:
- With the bucket name included in the hostname:
PUT /target-object-name HTTP/1.1
- With the bucket name following the hostname:
PUT /target-bucket-name/target-object-name HTTP/1.1
The next list describes the headers you can use in a request to copy an object.
Authorization
Specifies user credentials or requests anonymous access.
Content-Type
Specifies the Internet media type of the data being copied. Valid values are Internet media types (for example,
text/plain
,application/xml
, orimage/jpeg
).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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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-copy-source
Specifies the source bucket and object or object version, in this format:
/bucket-name/source-object-name[?versionId=source-object-version-id]
The initial forward slash (/) is required.
Valid values for source-object-version-id are the IDs of versions of the source object specified in the request.
The versionId query parameter is not case sensitive.
If you include the versionId query parameter in the
x-amz-copy-source
header with an invalid value while versioning is enabled, HCP returns a 404 (Not Found) status code and does not copy the object.If you include the versionId query parameter in the
x-amz-copy-source
header while versioning is disabled, the parameter is ignored, and the current version of the specified object is used as the source for the copy operation.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.
x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual
x-amz-grant-
headers to add the ACL, thex-amz-acl
header is invalid.x-amz-copy-source-if-match
Specifies one or more values for comparison with the ETag of the specified source 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 and does not copy the object.
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
x-amz-copy-source-if-match
header. All ETags match an asterisk in anx-amz-copy-source-if-match
header.x-amz-copy-source-if-modified-since
Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified source 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 412 (Precondition Failed) status code and does not copy the object.
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 x-amz-copy-source-if-modified-since header doesn’t conform to one of the formats shown above, the header is ignored.
- DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
x-amz-copy-source-if-none-match
Specifies one or more values for comparison with the ETag of the specified source 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 412 (Precondition Failed) status code and does not copy the object.
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
x-amz-copy-source-if-match
header. No ETags match an asterisk in anx-amz-copy-source-if-match
header.x-amz-copy-source-if-unmodified-since
Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified source 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 and does not copy the object.
For valid values for this header, see the description of the
x-amz-copy-source-if-modified-since
header above.x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-full-control
header is invalid.x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read
header is invalid.x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read-acp
header is invalid.x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write
header is invalid.x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write-acp
header is invalid.x-amz-meta-
Adds custom metadata to the target object.
x-amz-metadata-directive
Tells HCP whether to use the custom metadata, if any, for the source object or object version as the custom metadata for the target object or to use the custom metadata, if any, specified in the copy request. Valid values are:
COPY
Use the custom metadata for the source object or object version.
REPLACE
Use the custom metadata specified in the copy request.
These values are case sensitive.
The default is COPY.
x-amz-server-side-encryption
Requests that the response headers include
x-amz-server-side-encryption
, which indicates whether objects stored in HCP are encrypted. The value of thex-amz-server-side-encryption
request header can be any character string.x-hcp-pretty-print
Optionally, requests that the XML response body be formatted for readability. Valid values are:
true
Format the XML response body for readability.
false
Do not apply any special formatting to the XML response body.
The default is false.
The values
true
andfalse
are not case sensitive.x-hcp-labelretentionhold
Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold-value pairs.
id
Unique label name. The maximum label size is 64 characters.
hold
Either
true
orfalse
.
Examples
- Place two labeled holds on the object.
x-hcp-labelretentionhold [{"id":"LabelHold-1","hold":true}, {"id":"LabelHold-2","hold":true}]
- Remove a labeled hold from the object.
x-hcp-labelretentionhold [{"id":"LabelHold-2","hold":false}]
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. This value can be either
true
orfalse
.
The list below describes the headers returned in response to a successful request to copy an object.
Content-Type
Specifies the Internet media type of the response body. For a request to copy an object, the value of this header is always
application/xml;charset=UTF-8
.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.
Transfer-Encoding
Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always
chunked
.x-amz-copy-source-version-id
Specifies the version ID of the source object. This header is returned only while versioning is enabled for the source bucket.
x-amz-server-side-encryption
Specifies whether objects stored in HCP are encrypted. Possible values are:
- If objects are encrypted,
AES256
- If objects are not encrypted,
None
This header is returned only if the request headers include
x-amz-server-side-encryption
.- If objects are encrypted,
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.
HCP returns information about the target object that results from a successful copy request in an XML response body.
The next list describes the XML elements in the response body returned in response to a request to copy an object. The elements are listed in alphabetical order.
CopyObjectResult
Root element.
ETag
Child of the
CopyObjectResult
element.The
ETag
element specifies the ETag for the target object.LastModified
Child of the
CopyObjectResult
element.The
LastModified
element specifies the date and time when the target object was last modified, in Greenwich Mean Time (GMT). The date and time are expressed in this format:yyyy-MM-ddTHH:mm:ss.SSSZ
For example:
2020-02-18T19:46:03.856Z
Modifying an object means modifying its metadata. You cannot modify the content of an object.
The table below describes HTTP status codes that can be returned in response to a request to copy an object.
Code | Meaning | Description |
200 | OK | HCP successfully copied the object. |
400 | Bad Request | Possible reasons include that an ACL grant header specifies an invalid grantee. |
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
409 | Conflict |
One of these:
|
412 | Precondition Failed |
One of these:
|
413 | Request Entity Too Large | The source object you are trying to copy is too big for the amount of space left in the target bucket. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
501 | Not Implemented | The request includes the x-amz-acl header with an invalid value. |
503 | Service Unavailable |
Possible reasons include:
If this error persists, contact your tenant administrator. |
Here is a sample PUT request that conditionally copies the current version of an object named campaigns/GoGetEm.xls from the sales-mktg bucket to the finance bucket, where the target object that results from the copy operation is named mktg/campaign_GoGetEm_expenses.xls. The request is being made while versioning is enabled for both the source and target buckets.
For the purpose of this example, assume that mktg/campaign_GoGetEm_expenses.xls already exists in the target bucket with an ETag of 7ad452af1e2f61b33a865c4362be5921. The request directs HCP to perform the copy operation only if the ETag of the source object doesn't match the ETag of the most recent version of the target object.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/sales-mktg/campaigns/GoGetEm.xls -- -k "https://finance.europe.hcp.example.com/mktg/campaign_GoGetEm_expenses.xls" -H "x-amz-copy-source-if-none-match:7ad452af1e2f61b33a865c4362be5921" -H "x-hcp-pretty-print: true"
Request headers
PUT /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:oBVRqkcjktavqo6z1m+chHhRmmI= x-amz-copy-source: /sales-mktg/campaigns/GoGetEm.xls x-amz-copy-source-if-none-match:7ad452af1e2f61b33a865c4362be5921 x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT x-amz-version-id: 87288825190337 ETag: "6ed7faad1e0661c03ad65a4317d4a94c" x-amz-copy-source-version-id: 87388217426433 Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2017-02-23T17:19:26.402Z</LastModified> <ETag>"6ed7faad1e0661c03ad65a4317d4a94c"</ETag> </CopyObjectResult>
Here is a sample PUT request that copies an old version of an object to the same object, thereby creating a new current version from the old version. The object in question is named AcctgBestPractices.doc and is in the finance bucket. The version ID of the version being copied is 87288808614529. The request is being made while versioning is enabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/finance/ AcctgBestPractices.doc?versionId=87288808614529 -- -k "https://finance.europe.hcp.example.com/AcctgBestPractices.doc" -H "x-hcp-pretty-print: true"
Request headers
PUT /AcctgBestPractices.doc HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:AZ/GOgJJXFh7K1pr59bIlwRUrc0= x-amz-copy-source: /finance/AcctgBestPractices.doc?versionId=87288808614529 x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT x-amz-version-id: 87288815588289 ETag: "764f38262c6e581f678e1ac9b0211ae8" x-amz-copy-source-version-id: 87288808614529 Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2017-02-23T17:19:26.000Z</LastModified> <ETag>"764f38262c6e581f678e1ac9b0211ae8"</ETag> </CopyObjectResult>
Here is a sample PUT request that replaces the existing custom metadata for the object named hum_res/budget_proposals/BudgProp-2020 in the finance bucket with new custom metadata. The request is being made while versioning is disabled for the bucket, so the custom metadata is replaced on the current version of the object. No new version is created.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/finance/hum_res/budget_proposals/BudgProp-2020 -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020" -H "x-amz-meta-author: Robin Silver" -H "x-amz-meta-department: Human Resources" -H "x-amz-metadata-directive: REPLACE" -H "x-hcp-pretty-print: true"
Request headers
PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:WAamEr9PkL76M/kWkFu5K2rY9Bs= x-amz-copy-source: /finance/hum_res/budget_proposals/BudgProp-2020 x-amz-meta-author: Robin Silver x-amz-meta-department: Human Resources x-amz-metadata-directive: REPLACE x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2017-02-23T17:19:26.062Z</LastModified> <ETag>"76216527ff2f6219f7c29251a619c8db"</ETag> </CopyObjectResult>
Here is a sample PUT request that updates the retention setting for the object named hum_res/budget_proposals/BudgProp-2020 in the finance bucket. In this example, the retention value of the object is set to five days past the time when the object was stored. The request is made while versioning is disabled for the bucket, so the retention value is replaced on the current version of the object. No new version is created.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/finance/hum_res/budget_proposals/BudgProp-2020 -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020" -H "x-hcp-retention: A+5d" -H "x-amz-metadata-directive: REPLACE" -H "x-hcp-pretty-print: true"
Request headers
PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:WAamEr9PkL76M/kWkFu5K2rY9Bs= x-amz-copy-source: /finance/hum_res/budget_proposals/BudgProp-2020 x-hcp-retention: A+5d x-amz-metadata-directive: REPLACE x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2017-02-23T17:19:26.062Z</LastModified> <ETag>"76216527ff2f6219f7c29251a619c8db"</ETag> </CopyObjectResult>
Here is a sample PUT request that updates the retention hold setting for the object named hum_res/budget_proposals/BudgProp-2020 in the finance bucket. In this example, the retention hold value of the object is modified from false
to true
. The request is being made while versioning is disabled for the bucket, so the retention hold value is replaced on the current version of the object. No new version is created.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/finance/hum_res/budget_proposals/BudgProp-2020 -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020" -H "x-hcp-retentionhold: true" -H "x-amz-metadata-directive: REPLACE" -H "x-hcp-pretty-print: true"
Request headers
PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:WAamEr9PkL76M/kWkFu5K2rY9Bs= x-amz-copy-source: /finance/hum_res/budget_proposals/BudgProp-2020 x-hcp-retentionhold: true x-amz-metadata-directive: REPLACE x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2017-02-23T17:19:26.062Z</LastModified> <ETag>"76216527ff2f6219f7c29251a619c8db"</ETag> </CopyObjectResult>
Here is a sample PUT request that places a labeled hold on an exiting object namedhum_res/budget_proposals/BudgProp-2020 in the finance bucket. The labeled hold is placed on the current version of the object.
Request with s3curl command line
./s3curl.pl --id=lgreen --copysrc=/finance/hum_res/budget_proposals/BudgProp-2020 -- -v -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020" -H "x-hcp-retentionhold: true" -H 'x-hcp-labelretentionhold: [{"id":"UniqueLabelHold-1","hold":true}]' -H "x-amz-metadata-directive: REPLACE" -H "x-hcp-pretty-print: true"
Request headers
PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 26 June 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:WAamEr9PkL76M/kWkFu5K2rY9Bs= x-amz-copy-source: /finance/hum_res/budget_proposals/BudgProp-2020 X-HCP-RetentionHold: true X-HCP-LabelRetentionHold: true x-amz-metadata-directive: REPLACE x-hcp-pretty-print: true
Response headers
HTTP/1.1 200 OK Date: Fri, 26 June 2020 17:19:26 GMT Content-Type: application/xml;charset=UTF-8 Transfer-Encoding: chunked
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <LastModified>2020-06-12T17:19:26.062Z</LastModified> <ETag>"76216527ff2f6219f7c29251a619c8db"</ETag> </CopyObjectResult>
Conditionally copying an object
You can use the x-amz-copy-source-if-match
, x-amz-copy-source-if-none-match
, x-amz-copy-source-if-modified-since
, and x-amz-copy-source-if-unmodified-since
request headers to make copy requests conditional:
- The
x-amz-copy-source-if-match
andx-amz-copy-source-if-none-match
headers compare the ETag of the source 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
x-amz-copy-source-if-modified-since
andx-amz-copy-source-if-unmodified-since
headers compare the date and time the source object or object version was last modified to a date and time that you specify.
If the source object or object version:
- Meets all the conditions specified by the conditional headers included in the request, HCP performs the copy operation.
- Does not meet all the conditions specified by the conditional headers included in the request, HCP returns a 412 (Precondition Failed) status code and does not copy the object.
If a request includes multiple different conditional headers, HCP processes any x-amz-copy-source-if-match
and x-amz-copy-source-if-none-match
headers before any x-amz-copy-source-if-modified-since
or x-amz-copy-source-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 others.
x-amz-copy-source-if-modified-since
and x-amz-copy-source-if-unmodified-since
request headers are not compatible with s3curl.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.
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
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
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 anIf-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.- DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
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 anIf-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 theRange
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.
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). For a delete marker, this is the date and time when the delete marker was created.
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 themetapairs
element, or that the specified version ID identifies a delete marker and the deleted object version had an annotation. This header is returned only when applicable. The value is always1
(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
orfalse
is returned.For a user without privileged data access permission, the response header returns
true
orfalse
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
, thex-hcp-labelretentionhold-labels
header is not returned.
- If the response header returns
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-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
orfalse
is returned.
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 | The specified object version is a delete marker. |
206 | Partial Content | HCP successfully retrieved the data in the byte range specified by the Range header. |
304 | Not Modified |
One of these:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
409 | Conflict | Possible reasons include that the object data is currently being written to HCP. |
412 | Precondition Failed |
One of these:
|
416 | Requested Range Not Satisfiable |
The request included a
|
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. |
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
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
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
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
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
andIf-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
andIf-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
orIf-Unmodified-Since
header, HCP returns a 412 (Precondition Failed) status code and does not return the object data - An
If-None-Match
orIf-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.
Deleting an object or folder
You use the HTTP DELETE method to delete an object or folder in a bucket. To delete an object, you need delete permission for the bucket containing the object or for the object itself. To delete a folder, you need delete permission for the bucket.
- You cannot delete an object or any version of that object if the object is under retention or on hold.
- When you delete an object while versioning is enabled, HCP:
- Retains the current version of the object as an old version. The version ID does not change.
- Creates a delete marker as the new current version of the object. A delete marker is a special version of an object that indicates that a version of the object has been deleted.
A delete marker has a version ID but does not have any data or metadata. When you delete an object while versioning is enabled, the version ID of the delete marker is different from the version ID of the object you deleted.
- When you delete an object while versioning is disabled, HCP changes the current version of the object to a delete marker and does not change the version ID.
- If you try to delete an object where the current version is a delete marker, HCP returns a 204 (No Content) status code.
- If you inadvertently delete an object, you can recover it from an old version. You can recover an object only while versioning is enabled.
To recover an object, use a PUT request to copy the object to itself. Use the versionId query parameter with the source object specification to specify which version of the object you want to use for recovery.
You cannot use a delete marker to recover an object.
You cannot recover an object from an old version that has been pruned.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to delete an object, an object version, or a folder has either of these formats:
- With the bucket name included in the hostname:
DELETE /(object-name|(folder-name(/|%2F))) HTTP/1.1
- With the bucket name following the hostname:
DELETE /bucket-name/(object-name|(folder-name(/|%2F))) HTTP/1.1
The list below describes the headers you can use in a request to delete an object, object version, or folder.
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
x-hcp-privileged
If you have privileged permission and the bucket allows it, this enables a privileged delete on an object that is under retention. The valid value for this header is a text string of up to 1,024 characters long, which can contain any valid UTF-8 characters, including white space.
The list below describes the headers returned in response to a successful request to delete an object, object version, or folder.
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
x-amz-delete-marker
Indicates either of these:
- The version of the object with the version ID specified by the
x-amz-version-id
header has been deleted. - The version of the object with the version ID that immediately precedes the version ID specified by the
x-amz-version-id
header has been deleted.
The value of this header is always
true
.This header is returned only while versioning is enabled for the bucket.
- The version of the object with the version ID specified by the
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.
The table below describes HTTP status codes that can be returned in response to a request to delete an object, object version, or folder.
Code | Meaning | Description |
204 | No Content |
One of these:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | Possible reasons include that the specified bucket does not exist. |
409 | Conflict |
Possible reasons include:
|
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. |
Here’s a sample DELETE request that deletes an object named hum_res/budget_proposals/BudgProp-2020 from the finance bucket.
The example shows the response headers HCP returns while versioning is enabled for the bucket and while versioning is disabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --delete -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/ BudgProp-2020"
Request headers
DELETE /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:i9bRonH4gi1SrymsF0Fw84mWUeQ=
Response headers with versioning enabled
HTTP/1.1 204 No Content Date: Fri, 07 February 2020 17:19:26 GMT x-amz-version-id: 87288781940929 x-amz-delete-marker: true
Response headers with versioning disabled
HTTP/1.1 204 No Content Date: Fri, 07 February 2020 17:19:26 GMT
Here’s a sample DELETE request that deletes a folder named hum_res/budget_proposals from the finance bucket. The request is being made while versioning is disabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --delete -- -k "https://finance.europe.hcp.example.com/hum_res/budget_proposals/"
Request headers
DELETE /hum_res/budget_proposals/ HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:6iZRgTyBmsiLxX37WDtIS8X7vT8=
Response headers
HTTP/1.1 204 No Content Date: Fri, 07 February 2020 17:19:26 GMT
Deleting multiple objects
You use the HTTP POST method to delete multiple objects in a bucket. To delete multiple objects, you need delete permission for the bucket containing the objects or for the objects themselves. You cannot use this method with the S3 compatible API to delete:
- Objects that are under retention.
- Objects that are on hold.
- Delete markers of objects.
- Multiple versions of objects.
Since the S3 compatible API currently does not support deleting multiple objects based on version ID, if you try to delete objects with multiple versions, only the current versions of the objects are deleted.
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to delete multiple objects has either of these formats:
- With the bucket name included in the hostname:
POST /?delete HTTP/1.1
- With the bucket name following the hostname:
POST /bucket-name?delete HTTP/1.1
The list below describes the headers you can use in a request to delete multiple objects.
Authorization
Specifies user credentials or requests anonymous access.
Content-MD5
Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.
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.
Content-Length
Specifies the size, in bytes, of the data being uploaded.
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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-amz-date
header.x-hcp-privileged
If you have privileged permission and the bucket allows it, this enables a privileged delete on an object that is under retention. The valid value for this header is a text string of up to 1,024 characters long, which can contain any valid UTF-8 characters, including white space.
The list below describes the XML elements in the request body to delete multiple objects. The elements are listed in alphabetical order.
Delete
Root element.
Key
Child of the
Object
element.The
Key
element specifies the name of the object to delete.Object
Child of the
Delete
element.The
Object
element specifies the delete request for an object.Quiet
Child of the
Delete
element.The
Quiet
element, when its value is set totrue
, enables quiet mode for the request.
The list below describes the headers returned in response to a successful request to delete multiple objects.
Content-Length
The size, in bytes, of the response body if HCP can determine the size before formulating the response.
If the response does not include a response body, the value of the
Content-Length
header is0
(zero).Content-Type
The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is
application/octet-stream
.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
HCP returns information about the objects that were successfully deleted and the objects that were not successfully deleted from a delete request in an XML response body.
The list below describes the XML elements in the response body returned in response to a request to delete multiple objects. The elements are listed in alphabetical order.
Code
Child of the
Error
element.The
Code
element specifies the status code for the error.DeleteMarker
Child of the
Deleted
element.The
DeleteMarker
element specifies whether the request accessed a delete marker.DeleteMarkerVersionId
Child of the
Deleted
element.The
DeleteMarkerVersionId
element specifies the version ID of the delete marker accessed by the request. Currently,Not Implemented
is returned with this element.DeleteResult
Root element.
Deleted
Child of the
DeleteResult
element.The
Deleted
element specifies the name of the object that the S3 compatible API successfully deleted.Error
Child of the
DeleteResult
element.The
Error
element specifies the name of the object that was not deleted and describes the error that was encountered.Key
Child of the
Deleted
element or theError
element.The
Key
element specifies the name of the object that the S3 compatible API attempted to delete.Message
Child of the
Error
element.The
Message
element provides more information about the error.VersionId
Child of the
Deleted
element or theError
element.The
VersionId
element specifies the version ID of the object that the S3 compatible API attempted to delete. The version ID of only the current version of the object is returned.
The table below describes HTTP status codes that can be returned in response to a request to delete multiple objects.
Code | Meaning | Description |
200 | OK | HCP has accepted the request. This does not mean that every object in the request was successfully deleted. |
204 | No Content |
One of these:
|
400 | Bad Request |
Possible reasons include:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | Possible reasons include that the specified object does not exist. |
409 | Conflict |
Possible reasons include:
|
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. |
Here’s a sample POST request on the finance bucket to delete objects named quarterly_rpts/Q2_2019.ppt and quarterly_rpts/Q3_2019.ppt.
Request with s3curl command line
./s3curl.pl --id=lgreen --contentType application/xml --calculateContentMd5 --post mod.xml -- -ik -v "https://europe.hcp.example.com/finance?delete"
Request headers
POST /finance?delete HTTP/1.1 Host: europe.hcp.example.com/finance Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:i9bRonH4gi1SrymsF0Fw84mWUeQ= Content-type: application/xml Content-MD5: BQ7HxZ32wHoDbnACnRE79w== Content-Length: 275
Request body
<?xml version="1.0" encoding="UTF-8"?> <Delete> <Object> <Key>quarterly_rpts/Q2_2019.ppt</Key> </Object> <Object> <Key>quarterly_rpts/Q3_2019.ppt</Key> </Object> </Delete>
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Content-Type: application/xml Content-Length: 731
Response body
<?xml version="1.0" encoding="UTF-8"?> <DeleteResult> <Deleted> <Key>quarterly_rpts/Q2_2019.ppt</Key> <VersionId>97302435810137</VersionId> <DeleteMarker>true</DeleteMarker> <DeleteMarkerVersionId>Not Implemented</DeleteMarkerVersionId> </Deleted> <Error> <Key>quarterly_rpts/Q3_2019.ppt</Key> <Code>AccessDenied</Code> <Message>Access Denied</Message> </Error> </DeleteResult>