Skip to main content
Hitachi Vantara Knowledge

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.

Request line

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
Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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, or image/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, the x-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 include x-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 the x-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 or false.

    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 or false.

Response headers

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.

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Return codes

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

CodeMeaningDescription
200OK

Possible reasons include:

  • HCP successfully stored the object.
  • The application attempts to set a labeled hold on an object with an HCP version earlier than 9.1.
  • The application puts the same labeled hold ID on the same object multiple times.
  • The application attempts to remove a nonexistent labeled hold ID from an object.
400Bad Request

Possible reasons include:

  • An ACL grant header specifies an invalid grantee.
  • The value specified by the Content-MD5 header does not match the Base64-encoded MD5 hash of the data HCP received.
  • The labeled hold ID length exceeds 64 characters.
  • A label hold ID must have at least one character.
  • The request contains over 100 labeled holds.
  • The active labeled hold limit exceeds 100 labels.
  • A request cannot specify the same labeled hold ID as both active and inactive.
  • The request must specify the labeled hold id and hold values.
  • To use the labeled hold feature, an online upgrade is required to HCP 9.1 or later.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to store objects in the specified bucket.
  • An object with the specified name already exists in the specified bucket, and versioning is enabled for that bucket, but the existing object is under retention or on hold.
  • The application tried to delete an object on labeled hold.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

Possible reasons include:

  • The specified bucket or object does not exist.
  • The specified object ID is invalid or the object does not exist.
409Conflict

One of these:

  • An object with the specified name already exists in the specified bucket, and versioning is disabled for the bucket.
  • A folder with the specified name already exists in the specified bucket.
411Length RequiredEither the request does not include a Content-Length header, or the request includes a Content-Length header with no value.
413Request Entity Too LargeThe object you are trying to store is too big for the amount of remaining space in the bucket.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

501Not ImplementedThe request includes the x-amz-acl header with an invalid value.
503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Storing an object

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
Storing an object with a labeled hold

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
Example: Storing an object with custom metadata and an ACL

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 of x-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.

Request line

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
Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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.

Response headers

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.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to create a folder.

CodeMeaningDescription
200OKHCP successfully created the folder.
400Bad RequestPossible reasons include that the request does not include a Content-Length header.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to create folders in the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundThe specified bucket does not exist.
409ConflictAn object or folder with the specified name already exists.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Creating a folder

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.

Notes3curl does not support the use of the forward slash (/) as the terminator for the folder name in PUT requests to create a folder.

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.

Request line

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
Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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 an If-Match header.

  • If-Modified-Since

    Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified 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.

  • 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 an If-None-Match header.

  • If-Unmodified-Since

    Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified 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.

Response headers

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 the Content-Type header is always 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
  • 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 the metapairs 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 always 1 (one).

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

  • x-hcp-labelretentionhold

    Specifies whether the object is on labeled hold. A Boolean value of true or false is returned.

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

    For a user with privileged data access permission:

    • If the response header returns true, an additional header, x-hcp-labelretentionhold-labels, is returned.
    • If the response header returns false, the x-hcp-labelretentionhold-labels header is not returned
  • x-hcp-labelretentionhold-labels

    If the object is on labeled hold (x-hcp-labelretentionhold:true) and the user has privileged data access and read 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 or false is returned.

Return codes

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.

CodeMeaningDescription
200OKPossible reasons include:
  • The specified object, object version, delete marker, or folder exists.
  • The application tries to get the labeled holds on an object with an HCP version earlier than 9.1.
304Not Modified

One of these:

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

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have read permission for the specified bucket or object.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

One of these:

  • The specified object, object version, or folder does not exist.
  • The specified bucket does not exist.
409ConflictPossible reason includes that the object data is currently being written to HCP.
412Precondition Failed

One of these:

  • The request included an If-Match header, and the ETag for the specified object or object version does not match any of the values specified by the header.
  • The request included an If-Unmodified-Since header, and the specified object or object version was modified after the date and time specified by the header.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Checking the existence of an object

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
Example: Retrieving custom metadata for an object version

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
Example: Checking whether an object has been modified

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
Example: Checking the existence of a folder

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.

Request line

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.

Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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 and text/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, the x-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.

Response headers

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
Return codes

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to an object.

CodeMeaningDescription
200OKHCP successfully added the ACL to the object.
400Bad Request

Possible reasons include:

  • You are trying to add an ACL that contains more than one hundred permission grants.
  • A specified grantee does not exist.
  • The specified owner does not exist.
  • Two grants of the same permission specify the same grantee.
  • The x-amz-acl header specifies an invalid value.
  • An x-amz-grant- header specifies an invalid identifier type.
  • The XML in the ACL request body is malformed or contains an invalid value.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to add an ACL to the object.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

One of these:

  • The specified object does not exist.
  • The specified bucket does not exist.
409ConflictPossible reasons include that the object data is currently being written to HCP.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Adding an ACL to an object by using a canned ACL

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
Example: Adding an ACL to an object by using an ACL request body

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.

Request line

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.

Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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 and false are not case sensitive.

Response headers

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.

Return codes

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

CodeMeaningDescription
200OKHCP successfully retrieved the object ACL.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to read the object ACL.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

One of these:

  • The specified object does not exist.
  • The specified bucket does not exist.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Retrieving an object ACL

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.

Request line

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
Required headers

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, or image/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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-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.

Optional headers
  • 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, the x-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 an x-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.

  • 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 an x-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 the x-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 and false 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 or false.

    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 or false.

Response headers

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.

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Response body

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.

Return codes

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

CodeMeaningDescription
200OKHCP successfully copied the object.
400Bad RequestPossible reasons include that an ACL grant header specifies an invalid grantee.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to store objects in the target bucket.
  • An object with the specified target object name already exists in the specified target bucket, and versioning is enabled for that bucket, but the existing object is under retention or on hold.
  • The S3 compatible API is currently disabled for the source or target bucket.
  • The source object exists, but the HCP system does not have the source object data. Retry the request, targeting a different system in the replication topology.
  • The source object is in the process of being deleted.
404Not Found

One of these:

  • The specified source object version ID identifies a delete marker.
  • The current version of the specified source object is a delete marker, and the request did not specify a version ID.
  • The specified source bucket does not exist.
409Conflict

One of these:

  • An object with the specified target object name already exists in the target bucket, versioning is disabled for that bucket, and the copy request does not include an x-amz-metadata-directive header with a value of REPLACE.
  • A folder with the specified target object name already exists in the target bucket.
412Precondition Failed

One of these:

  • The request included an x-amz-copy-source-if-match header, and the ETag for the specified source object or object version does not match any of the values specified by the header.
  • The request included an x-amz-copy-source-if-none-match header, and the ETag for the specified source object or object version matched a value specified by the header.
  • The request included an x-amz-copy-source-if-modified-since header, and the specified source object or object version was not modified after the date and time specified by the header.
  • The request included an x-amz-copy-source-if-unmodified-since header, and the specified source object or object version was modified after the date and time specified by the header.
413Request Entity Too LargeThe source object you are trying to copy is too big for the amount of space left in the target bucket.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

501Not ImplementedThe request includes the x-amz-acl header with an invalid value.
503Service Unavailable

Possible reasons include:

  • The specified version of the source object is a delete marker.
  • HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Conditionally copying an object from one bucket to another

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>
Example: Recovering an old version of an object

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>
Example: Replacing custom metadata for an existing object

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>
Example: Setting retention for an existing object

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>
Example: Changing the retention hold value of an object

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>
Example: Placing a labeled hold on an object

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 and x-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 and x-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.

NoteThe 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.

Request line

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

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

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

  • Authorization

    Specifies user credentials or requests anonymous access.

  • Date

    Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

    The date and time must always be specified using Greenwich Mean Time (GMT).

    To specify the date and time, use this format:

    DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    In this format:

    • DDD

      The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

    • dd

      The two-digit day of the month.

    • MMM

      The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

    • yyyy

      The four-digit year.

    • HH

      The hour on a 24-hour clock.

    • mm

      The number of minutes.

    • ss

      The number of seconds.

    For example:

    Thu, 23 Mar 2017 14:27:05 +0000

    All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional request headers
  • If-Match

    Specifies one or more values for comparison with the ETag of the specified object or object version. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag does not match any of the specified values, HCP returns a 412 (Precondition Failed) status code.

    To specify the values for this header, use this format:

    "value"[, "value"]...

    In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

    Alternatively, you can specify a single asterisk (*) as the value for the If-Match header. All ETags match an asterisk in an If-Match header.

  • If-Modified-Since

    Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 304 (Not Modified) status code.

    To specify the date and time for this header, use one of these formats:

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

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

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

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

    • DDD MMM d HH:mm:ss yyyy

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

    If the value specified by the If-Modified-Since header doesn’t conform to one of the formats shown above, the header is ignored.

  • If-None-Match

    Specifies one or more values for comparison with the ETag of the specified object or object version. If the ETag doesn’t match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 304 (Not Modified) status code.

    To specify the values for this header, use this format:

    "value"[, "value"]...

    In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

    Alternatively, you can specify a single asterisk (*) as the value for the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

  • If-Unmodified-Since

    Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code.

    For valid values for this header, see the description of the If-Modified-Since header above.

  • Range

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

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

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

    Range: bytes=byte-range

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

    • start-position–end-position

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

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

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

    • start-position–

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

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

    • –offset-from-end

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

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

    These considerations apply to Range header values:

    • If you specify a valid range in which the start position is less than the size of the object data, HCP returns the requested range of data with a 206 (Partial Content) status code.
    • If you specify a valid range in which the start position is greater than or equal to the size of the object data, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.
    • If you specify an offset of zero, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.
    • If you specify an invalid value (for example, a value in which the start position is greater than the end position, HCP ignores the Range header and returns the complete object data with a status code of 200 (OK).

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

    You cannot retrieve a part of an in-progress multipart upload.

Response headers

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

  • Accept-Ranges

    Indicates that HCP can accept requests for part of the object data, specified as a range of bytes. The value of this header is always bytes.

  • Content-Length

    Specifies the size, in bytes, of the returned data.

  • Content-Range

    Specifies the range of bytes retrieved out of the total size of the object data. This header is returned only if the request headers include Range.

  • Content-Type

    Specifies the Internet media type of the object or object version. This is one of, in order of precedence:

    • The Internet media type specified by the response-content-type request parameter.
    • The Internet media type specified in the Content-Type header when the object was stored.
    • An Internet media type determined by HCP based on the object name.
    • application/octet-stream if HCP cannot determine the Internet media type.
  • Date

    The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

    DDD dd MMM yyyy HH:mm:ss GMT

    For example:

    Fri, 18 Sep 2020 14:27:05 GMT
  • ETag

    Specifies the ETag for the object.

    ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.

  • Last-Modified

    Specifies the date and time when the object or object version was last modified, in Greenwich Mean Time (GMT). 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 the metapairs 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 always 1 (one).

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

  • x-hcp-labelretentionhold

    Specifies whether the object is on labeled hold. Either true or false is returned.

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

    For a user with privileged data access permission:

    • If the response header returns true, an additional header, x-hcp-labelretentionhold-labels, is returned.
    • If the response header returns false, the x-hcp-labelretentionhold-labels header is not returned.
  • x-hcp-labelretentionhold-labels

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

    Example

    x-hcp-labelretentionhold-labels: [{"id":"UniqueLabelHold-1","hold": true},
    [{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]
  • x-hcp-retention

    Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

  • x-hcp-retentionhold

    Specifies whether the object is on hold. Either true or false is returned.

Return codes

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

CodeMeaningDescription
200OK

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.

204No ContentThe specified object version is a delete marker.
206Partial ContentHCP successfully retrieved the data in the byte range specified by the Range header.
304Not Modified

One of these:

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

Possible reasons include:

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

One of these:

  • The specified object or object version does not exist.
  • The current version of the specified object is a delete marker, and the request did not specify a version ID.
  • The specified item is a folder.
  • The specified bucket does not exist.
409ConflictPossible reasons include that the object data is currently being written to HCP.
412Precondition Failed

One of these:

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

The request included a Range header that specified either:

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

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Retrieving an object

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

Request with s3curl command line

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

Request headers

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

Response headers

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

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

Request with s3curl command line

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

Request headers

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

Response headers

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

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

Request with s3curl command line

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

Request headers

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

Response headers

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

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

Request with s3curl command line

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

Request headers

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

Response headers

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

Conditionally retrieving an object

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

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

  • The If-Match and If-None-Match headers compare the ETag for the requested object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.
  • The If-Modified-Since and If-Unmodified-Since headers compare the date and time the requested object or object version was last modified to a date and time that you specify.

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

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

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

Overriding response headers

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

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

Request headerResponse header
response-cache-controlCache-Control
response-content-dispositionContent-Disposition
response-content-encodingContent-Encoding
response content-languageContent-Language
response-content-typeContent-Type
response-expiresExpires

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.

Usage considerations
  • 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.

Request line

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
Required headers

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name
  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers
  • 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.

Response headers

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.

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to delete an object, object version, or folder.

CodeMeaningDescription
204No Content

One of these:

  • HCP successfully deleted the object or folder.
  • The specified object or folder does not exist.
  • The current version of the specified object is a delete marker.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have delete permission for the specified bucket or object.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundPossible reasons include that the specified bucket does not exist.
409Conflict

Possible reasons include:

  • The object data is currently being written to HCP.
  • The specified object is under retention.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Deleting an object

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
Example: Deleting a folder

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.

Request line

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
Required headers

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.

Optional headers
  • 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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-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.

Request body

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 to true, enables quiet mode for the request.

Response headers

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 is 0 (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
Response body

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 the Error 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 the Error 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.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to delete multiple objects.

CodeMeaningDescription
200OKHCP has accepted the request. This does not mean that every object in the request was successfully deleted.
204No Content

One of these:

  • HCP successfully deleted the object.
  • The specified object does not exist.
  • The current version of the specified object is a delete marker.
400Bad Request

Possible reasons include:

  • The request includes a header that is invalid for the requested operation.
  • The specified bucket name is invalid.
  • The specified object name is invalid.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have delete permission for the specified object.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundPossible reasons include that the specified object does not exist.
409Conflict

Possible reasons include:

  • The object data is currently being written to HCP.
  • The specified object is under retention.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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

If this error persists, contact your tenant administrator.

Example: Deleting multiple objects

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>

 

  • Was this article helpful?