Skip to main content
Hitachi Vantara Knowledge

Working with buckets

With the Hitachi API for Amazon S3, you can perform operations on individual buckets. You can also list all the buckets you own.

NoteTo perform these bucket activities, the management API must be enabled for the owning tenant:
  • Create a bucket
  • List the buckets you own
  • Enable, disable, or check the status of versioning for a bucket
  • Add, retrieve, or remove the ACL for a bucket
  • Delete a bucket

If you cannot perform these activities, contact your tenant administrator.

Creating a bucket

You use the HTTP PUT method to create a bucket. To create a bucket, you must be an authenticated user. Additionally, your user account must be configured to let you create buckets.

When you create a bucket, you specify a name for it. The specified name must be at least three characters long and at most 63 characters long. The name can contain only alphanumeric characters and hyphens (-) but cannot start or end with a hyphen.

You can specify an ACL for a bucket in the same request as you use to create the bucket. To do this, you need to use ACL headers. You cannot use an ACL request body when creating a bucket.

If the ACL you specify in a request to create a bucket is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not create the bucket.

When you create a bucket, you become the bucket owner. You also get browse, read, read ACL, write, write ACL, and delete data access permissions for the bucket. If search is enabled for the bucket, you also get search permission.

NoteYou cannot use Active Directory authentication with S3 compatible requests to create a bucket.
Request line

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

  • With the bucket name included in the hostname:
    PUT / HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name HTTP/1.1
Required headers
  • Authorization

    Specifies user credentials or requests anonymous access.

NoteYou cannot create a bucket as an anonymous user.
  • Content-Length

    Specifies the size, in bytes, of the request body. For a request to create a bucket, the value of this header must be 0 (zero).

  • 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
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-date

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

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

  • x-amz-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 create a bucket.

  • 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
  • Location

    Specifies the name of the bucket created by the request.

Return codes

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

CodeMeaningDescription
200OK

One of these:

  • The bucket was successfully created.
  • A bucket with the specified name already exists and is owned by you.
400Bad Request

Possible reasons include:

  • The specified bucket name is invalid.
  • An ACL grant header specifies an invalid grantee.
  • You already own the maximum number buckets allowed per user.
  • The tenant does not have enough space for another bucket.
  • The tenant already has the maximum number of buckets it’s allowed to have.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to create buckets.
  • The tenant does not currently support use of the S3 compatible API for creating buckets.
409ConflictA bucket with the specified name already exists and either is owned by a user other than you or has no owner.
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: Creating a bucket

Here’s a sample PUT request that creates a bucket named finance in the context of the tenant named europe.

Request with s3curl command line

./s3curl.pl --id=lgreen --createBucket -- -k "https://finance.europe.hcp.example.com"

Request headers

PUT / HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:1RXSNMipYpv4IOpfNS9Odi1UBWM=
Content-Length: 0

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Location: /finance
Content-Length: 0
Example: Creating a bucket with an ACL

Here’s a sample PUT request that creates a bucket named human-resources and adds an ACL to the bucket. The ACL grants read permission to all users and write permission to the users with usernames mwhite and pdgrey.

Request with s3curl command line

./s3curl.pl --id=lgreen --createBucket -- -k
     "https://human-resources.europe.hcp.example.com"
     -H "x-amz-grant-read: emailAddress=all_users"
     -H "x-amz-grant-write: emailAddress=mwhite, emailAddress=pdgrey"

Request headers

PUT / HTTP/1.1
Host: human-resources.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:0WCfi79j2QtCczA6TGutnJWNRm4=
x-amz-grant-read: emailAddress=all_users
x-amz-grant-write: emailAddress=mwhite, emailAddress=pdgrey
Content-Length: 0

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Location: /human-resources
Content-Length: 0

Listing the buckets you own

You use the HTTP GET method to list the buckets you own. To list the buckets you own, you must be an authenticated user.

The target of a request to list the buckets you own is a tenant (that is, the service point). The list of buckets in the response contains only buckets created in the context of that tenant and only those that have the S3 compatible API enabled. The buckets are listed in alphanumeric order.

The list of buckets you own is returned in an XML response body.

Request line

An S3 compatible request to list the buckets you own has this format:

GET / HTTP/1.1
Required headers
  • 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
  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, 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.

Response body

HCP returns the list of buckets you own in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>bucket-owner-user-id</ID>
          <DisplayName>bucket-owner-username</DisplayName>
     </Owner>
     <Buckets>
Format for a bucket:
          <Bucket>
               <Name>bucket-name</Name>
               <CreationDate>bucket-creation-date-and-time</CreationDate>
          </Bucket>
            .
            .
            .
     </Buckets>
</ListAllMyBucketsResult>
  • Bucket

    Child of the ListAllMyBucketsResult element and container for the Name and CreationDate elements.

    The response body contains one Bucket element for each bucket you own.

  • CreationDate

    Child of the Bucket element.

    The CreationDate element specifies the date and time when the applicable bucket was created, 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
  • DisplayName

    Child of the Owner element.

    If the bucket owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the bucket owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.

  • ID

    Child of the Owner element.

    If the bucket owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the bucket owner is identified by an AD user account, the value of the ID element is the SID for that account.

  • ListAllMyBucketsResult

    Root element.

  • Name

    Child of the Bucket element.

    The Name element specifies the name of a bucket.

  • Owner

    Child of the ListAllMyBucketsResult element and container for the DisplayName and ID elements.

    The Owner element identifies the owner of the applicable bucket.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to list the buckets you own.

CodeMeaningDescription
200OKHCP successfully retrieved the list of buckets you own.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • The tenant does not currently support use of the S3 compatible API for listing the buckets you own.
  • The specified tenant 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: Listing the buckets you own

Here’s a sample GET request that returns a list of the buckets owned by user lgreen in the context of the europe tenant.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://europe.hcp.example.com"
     -H "x-hcp-pretty-print: true"

Request headers

GET / HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:Gek+OrFpyg06Bufgg+TW6kH5ISA=
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"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
          <DisplayName>lgreen</DisplayName>
     </Owner>
     <Buckets>
          <Bucket>
               <Name>finance</Name>
               <CreationDate>2019-03-18T12:59:11.898Z</CreationDate>
          </Bucket>
          <Bucket>
               <Name>human-resources</Name>
               <CreationDate>2019-03-18T19:46:03.856Z</CreationDate>
          </Bucket>
     </Buckets>
</ListAllMyBucketsResult>

Checking the existence of a bucket

You use the HTTP HEAD method to check the existence of a bucket. To successfully check the existence of a bucket, you need read permission for the bucket.

If the bucket you specify in the HEAD request does not exist, HCP returns a 404 (Not Found) status code. If the bucket exists but you do not have read permission for it, 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 a bucket has either of these formats:

  • With the bucket name included in the hostname:
    HEAD / HTTP/1.1
  • With the bucket name following the hostname:
    HEAD /bucket-name HTTP/1.1
Required headers
  • 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.

Response headers
  • 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
Return codes

The table below describes HTTP status codes that can be returned in response to a request to check the existence of a bucket.

CodeMeaningDescription
200OKThe specified bucket exists.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • The specified bucket exists, but you do not have read permission for it.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The tenant does not currently support use of the S3 compatible API for checking bucket existence.
404Not FoundThe 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: Checking the existence of a bucket

Here’s a sample HEAD request that checks the existence of a bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k "https://finance.europe.hcp.example.com"

Request headers

HEAD / HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:N2UfjwTaydEqS45O5vgcoGerZKw=

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Length: 0

Adding an ACL to a bucket

You use the HTTP PUT method with the acl query parameter to add an ACL to an existing bucket. Adding an ACL to a bucket replaces any existing ACL in its entirety. You cannot modify an existing ACL in place.

To add an ACL to a bucket, you need write ACL permission for the bucket.

To add an ACL to a bucket, 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 a bucket you own. You cannot use ACL headers to do this. To change the owner of a bucket, you need both write ACL 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 bucket.

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 a bucket has either of these formats:

  • With the bucket name included in the hostname:
    PUT /?acl HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

Required headers
  • Authorization

    Specifies user credentials or requests anonymous access.

  • 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 the bucket. If you’re using ACL headers to add the ACL, the Content-Length header is invalid.

  • 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. 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 a bucket.

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

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

CodeMeaningDescription
200OKHCP successfully added the ACL to the bucket.
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 bucket.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket..
  • The tenant does not currently support use of the S3 compatible API for adding ACLs to a buckets.
404Not FoundThe 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: Adding an ACL to a bucket by specifying individual grants

Here’s a sample PUT request that adds an ACL to the finance bucket by using x-amz-grant- headers. The ACL grants read permission to all users, write permission to user pdgrey, and write, read ACL, and write ACL permission to user mwhite.

Request with s3curl command line

./s3curl.pl --id=lgreen --put ~ -- -k "https://europe.hcp.example.com/finance?acl"
     -H "x-amz-grant-read: emailAddress=all_users"
     -H "x-amz-grant-write: emailAddress=pdgrey, emailAddress=mwhite"
     -H "x-amz-grant-read-acp: emailAddress=mwhite"
     -H "x-amz-grant-write-acp: emailAddress=mwhite"

Request headers

PUT /finance?acl HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:RuKD8rwRevmwLo+ZMhF5beGq7Qk=
x-amz-grant-read: emailAddress=all_users
x-amz-grant-write: emailAddress=pdgrey, emailAddress=mwhite
x-amz-grant-read-acp: emailAddress=mwhite
x-amz-grant-write-acp: emailAddress=mwhite

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Length: 0
Example: Adding an ACL to a bucket by using an ACL request body

Here’s a sample PUT request that uses an ACL request body to add an ACL to the finance bucket and, at the same time, change the owner of the bucket. The ACL grants read and write access to the bucket to user lgreen and changes the bucket owner to user mwhite. The ACL request body is in a file named acl-7.xml.

Request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
          <DisplayName>mwhite</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>READ</Permission>
          </Grant>
          <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>WRITE</Permission>
          </Grant>
      </AccessControlList>
</AccessControlPolicy>

Request with s3curl command line

./s3curl.pl --id=lgreen --put acl-7.xml -- -k
     "https://europe.hcp.example.com/finance?acl"

Request headers

PUT /finance?acl HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:mVNu4YolbdvK+PVzmafhOvd1VgU=
Content-Length: 727

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Content-Length: 0

Retrieving the ACL for a bucket

You use the HTTP GET method with the acl query parameter to retrieve the ACL for a bucket. To perform this action, you must have read ACL permission for the bucket.

The bucket 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 API request, a request to retrieve a bucket ACL has either of these formats:

  • With the bucket name included in the hostname:
    GET /?acl HTTP/1.1
  • With the bucket name following the hostname:
    GET /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

Required headers
  • 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 next list describes the headers returned in response to a successful request to retrieve a bucket ACL.

  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, 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 next table describes HTTP status codes that can be returned in response to a request to retrieve a bucket ACL.

CodeMeaningDescription
200OKHCP successfully retrieved the bucket ACL.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to read the bucket ACL.
  • The specified bucket does not currently support the requested operation.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The tenant does not currently support use of the S3 compatible API for retrieving bucket ACLs.
404Not FoundThe 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 a bucket ACL

Here is a sample GET request that retrieves the ACL for the bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?acl"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?acl HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:Msry4PBtztkM6FMvzdDblC5RoPE=
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="Group"
                 mlns: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="Group"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
               </Grantee>
               <Permission>READ</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
               <DisplayName>mwhite</DisplayName>
          </Grantee>
          <Permission>READ_ACP</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
               <DisplayName>mwhite</DisplayName>
               </Grantee>
               <Permission>WRITE_ACP</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
                    <DisplayName>mwhite</DisplayName>
               </Grantee>
               <Permission>WRITE</Permission>
          </Grant>
          <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="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <ID>b9d39144-a081-4763-b0e8-b8fb51e10192</ID>
                    <DisplayName>pdgrey</DisplayName>
               </Grantee>
               <Permission>WRITE</Permission>
          </Grant>
      </AccessControlList>
</AccessControlPolicy>

Enabling or disabling versioning for a bucket

You use the HTTP PUT method with the versioning query parameter to enable or disable versioning for a bucket. To enable or disable versioning for a bucket, you need to be the bucket owner.

While versioning is enabled for a bucket, the versioning status of the bucket is Enabled. If you disable versioning for a bucket after it has been enabled, the versioning status changes to Suspended. If versioning has never been enabled for a bucket, the bucket has no explicit versioning status.

To enable or disable versioning for a bucket, you specify the new versioning status in an XML request body.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to enable or disable versioning for a bucket has either of these formats:

  • With the bucket name included in the hostname:
    PUT /?versioning HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name?versioning HTTP/1.1

The versioning query parameter is not case sensitive.

Required headers
  • Authorization

    Specifies user credentials or requests anonymous access.

  • Content-Length

    Specifies the size, in bytes, of the request body.

  • 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 values are application/xml and text/xml.

Request body

For the content of a versioning request body, you use XML in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VersioningConfiguration
     xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>versioning-status</Status>
</VersioningConfiguration>

The list below describes the XML elements in a versioning request body. The elements are listed in alphabetical order.

  • Status

    Child of the VersioningConfiguration element. Valid values for the Status element are:

    • Enabled

      Enables versioning for the bucket

    • Suspended

      Disables versioning for the bucket

  • VersioningConfiguration

    Root element. This must be the first element in the versioning request body.

    The VersioningConfiguration element can optionally include this XML namespace specification:

    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
Response headers

The list below describes the headers returned in response to a successful request to enable or disable versioning for a bucket.

  • 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
  • Location

    Specifies the name of the target bucket.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to enable or disable versioning for a bucket.

CodeMeaningDescription
200OKHCP successfully enabled or disabled versioning for the bucket.
400Bad RequestPossible reasons include that the XML in the versioning request body is malformed or contains an invalid value.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You are not the bucket owner.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The tenant does not currently support use of the S3 compatible API for enabling or disabling bucket versioning.
404Not FoundThe 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: Enabling versioning for a bucket

Here’s a sample PUT request that enables versioning for the finance bucket. The versioning request body is in a file named versioning.xml.

Request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Status>Enabled</Status>
</VersioningConfiguration>

Request with s3curl command line

./s3curl.pl --id=lgreen --put versioning.xml -- -k
     "https://europe.hcp.example.com/finance?versioning"

Request headers

PUT /finance?versioning HTTP/1.1
Host: europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:ETdibK607bVlNdxb0aKCttJU33U=
Content-Length: 182

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Location: /finance
Content-Length: 0

Checking the versioning status of a bucket

You use the HTTP GET method with the versioning query parameter to check the versioning status of a bucket. To check the versioning status of a bucket, you need to be the bucket owner.

The versioning status is returned in an XML response body. The format of the response body is the same as the format you use for the versioning request body when you enable or disable versioning for a bucket.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to check the versioning status of a bucket has either of these formats:

  • With the bucket name included in the hostname:
    GET /?versioning HTTP/1.1
  • With the bucket name following the hostname:
    GET /bucket-name?versioning HTTP/1.1

The versioning query parameter is not case sensitive.

Required headers
  • 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 check the versioning status of a bucket.

  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, 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 check the versioning status of a bucket.

CodeMeaningDescription
200OKHCP successfully retrieved the versioning status.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You are not the bucket owner.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The tenant does not currently support use of the S3 compatible API for retrieving the versioning status of a bucket.
404Not FoundThe 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: Checking the versioning status of a bucket

Here’s a sample GET request that retrieves the versioning status of the bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?versioning"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?versioning HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:2rmMzjz+08PWDb/4Kd1nD43Wf1s=
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"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Status>Enabled</Status>
</VersioningConfiguration>

Listing bucket contents (version 1)

You use the HTTP GET method to list the contents of a bucket. To list the contents of a bucket, you need browse permission for the bucket. You do not need to be an authenticated user.

For the purpose of a bucket listing, the bucket contents consist not only of the objects you stored in the bucket but also of the folders that you created in the bucket or that HCP created automatically from the object names. For example, by default, if a bucket contains an object named quarterly_rpts/Q4_2019, a list of the bucket contents includes these two items:

  • quarterly_rpts/
  • quarterly_rpts/Q4_2019

By default, a bucket listing includes only the current (or only) versions of objects. To request a listing that includes old versions of objects, you use the versions query parameter.

A listing that includes versions of objects may include delete markers. A delete marker indicates that a version of the object was deleted.

A bucket listing is returned in an XML response body. In the response body, items in the bucket listing occur in ascending alphanumeric order by item name. If the listing includes multiple versions of an object, those versions are listed in ascending chronological order by last-modified time.

Request line

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

  • With the bucket name included in the hostname:
    GET /[?[versions][query-parameters]] HTTP/1.1
  • With the bucket name following the hostname:
    GET /bucket-name[?[versions][query-parameters]] HTTP/1.1

The versions query parameter is not case sensitive.

query-parameters can be none, one, or more of:

  • delimiter

    You use the delimiter query parameter to request a bucket listing that includes a list of common prefixes, where a prefix is the name of an item up through the first occurrence of the character string specified by the delimiter parameter. Each common prefix is listed only once regardless of the number of items with matching names. The items with matching names are not included elsewhere in the listing.

    The returned listing also contains items with names that do not include the character string specified by the delimiter parameter. In the listing, all the named items are listed first, followed by all the common prefixes.

    The items and common prefixes included in a listing are subject to any other criteria specified in the request.

    Both the items and the common prefixes count toward the maximum number of items that can be included in the bucket listing.

    The list of items does not include in-progress multipart uploads. The list of common prefixes does not include common prefixes that are exclusively for multipart uploads.

    The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The delimiter parameter name and the character string you specify are both case sensitive.

  • encoding-type

    You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

    The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

    The encoding-type parameter name is case sensitive.

  • prefix

    You use the prefix query parameter to request a bucket listing that contains only items with names that begin with a specified character string (the prefix) and, if applicable, common prefixes that begin that prefix.

    For example, the bucket listing returned in response to a GET request with the prefix=sales query parameter contains only these items:

    sales/
    sales/budget_proposals/
    sales/budget_proposals/BudgProp-2020
    sales_quotas_2020.pdf

    The list of items does not include in-progress multipart uploads or common prefixes that are exclusively for multipart uploads.

    The character string you specify for the prefix query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The prefix parameter name and the character string you specify are both case sensitive.

  • max-keys

    By default, a bucket listing can include at most one thousand items. However, you can use the max-keys query parameter in a bucket listing request to specify a smaller maximum number of items. If more than the maximum number of items satisfy the criteria for a request, you can use query parameters to retrieve the parts in groups.

    For example, the bucket listing returned in response to a GET request with the max-keys=6 query parameter contains these items:

    AcctgBestPractices.doc (current version)
    acctg/
    acctg/AcctgRR-Summary
    acctg/budget_proposals/
    acctg/budget_proposals/BudgProp-2020
    hum_res/

    Valid values for the max-keys query parameter are integers in the range 0 (zero) through 2,147,483,647. If you specify an integer greater than one thousand, the returned bucket listing includes only the first one thousand items that satisfy the request criteria (or fewer if fewer than one thousand items satisfy the criteria).

    The max-keys parameter name is case sensitive.

  • marker

    You use the marker query parameter to start the returned bucket listing with the first item with a name that comes alphanumerically after the character string specified by the marker parameter.

    For example, the bucket listing returned in response to a GET request with the marker=quarterly_rpts/ query parameter contains these items:

    quarterly_rpts/Q2_2019.ppt
    quarterly_rpts/Q3_2019.ppt
    quarterly_rpts/Q4_2019.ppt
    sales/
    sales/budget_proposals/
    sales/budget_proposals/BudgProp-2020
    sales_quotas_2020.pdf

    When more than the requested number of items satisfy the criteria in a request for a bucket listing, HCP returns a partial listing. In this case, the response body includes the IsTruncated element with a value of true. You can request the next part of the listing by including the marker query parameter in a new request. As the parameter value, you specify either the name of the last item in the returned listing or the last common prefix in the returned listing, whichever is alphanumerically greater.

    If the string you specify as the value of the marker query parameter is the name of a folder and does not end with a forward slash (/), items that begin with that string followed by a forward slash are omitted from the listing.

    The character string you specify for the marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The marker parameter name and the character string you specify are both case sensitive.

    The marker parameter is ignored if specified in a GET request that includes the versions parameter.

  • version-id-marker

    You use the version-id-marker parameter in conjunction with the key-marker parameter to start the returned bucket listing with the first item with:

    • A name that’s equal to the character string specified by the key-marker parameter
    • A version ID that’s greater than the value specified by the version-id-marker parameter

    If no such item exists, the returned bucket listing starts with the first item with a name that's alphanumerically greater than the character string specified by the key-marker parameter.

    For example, the version ID of the first version of the object named mktg/campaign_GoGetEm_expenses.xls is 87288784288321. The bucket listing returned in response to a GET request with the key-marker=mktg/campaign_GoGetEm_expenses.xls and version-id-marker=87288784288321 query parameters contains only these items:

    mktg/campaign_GoGetEm_expenses.xls (second version)
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/Q2_2019.ppt
    quarterly_rpts/Q3_2019.ppt
    quarterly_rpts/Q4_2019.ppt
    sales/
    sales/budget_proposals/
    sales/budget_proposals/BudgProp-2020
    sales_quotas_2020.pdf

    When the response body for a version listing request includes the IsTruncated element with a value of true, the response body also includes the NextKeyMarker and NextVersionIdMarker elements. If the alphanumerically last item in the version listing is:

    • Is a named item, the values of the NextKeyMarker and NextVersionIdMarker elements are the name and version ID of that item, respectively
    • Is a common prefix, the value the NextKeyMarker element is that prefix, and NextVersionIdMarker is an empty element.

    To request the next part of the listing, you include the key-marker and version-id-marker query parameters in a new request. For the value of the key-marker parameter, you use the value of the NextKeyMarker element from the previously returned listing. For the value of the version-id-marker parameter, you use the value of the NextVersionIdMarker element from the previously returned listing.

    Valid values for the version-id-marker query parameter are integers greater than or equal to zero.

    The version-id-marker parameter name is case sensitive.

Request headers

The list below describes the headers you can use in a request to list the contents of a bucket.

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

  • 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 list the contents of a bucket.

  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, 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.

Response body

The response body returned in response to a request to list the contents of a bucket differs depending on whether request is for the current (or only) versions of objects or for object versions.

The list below describes the XML elements in the two formats of the response body returned in response to a request to list the contents of a bucket. The elements are listed in alphabetical order.

  • CommonPrefixes

    Child of the ListBucketResult or ListVersionsResult element and container for the Prefix element.

    The response body contains one CommonPrefixes element for each common prefix in the bucket listing.

  • Contents

    Child of the ListBucketResult element and container for the elements that describe a current item in the bucket.

    The response body contains one Contents element for each item that satisfies the request criteria.

  • DeleteMarker

    Child of the ListVersionsResult element and container for the elements that describe a delete marker.

    The response body contains one DeleteMarker element for each delete marker that satisfies the request criteria.

  • Delimiter

    Child of the ListBucketResult or ListVersionsResult element.

    The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.

  • DisplayName

    Child of the Owner element.

    If the item owner is identified by an HCP user account, the value of the DisplayName element is the user name for that account. If the item owner is identified by an AD user account, the value of the DisplayName element is the user name of that account followed by an at sign (@) and the AD domain name.

    If the item has no owner, the value of the DisplayName element is nobody.

    For folders, the value of the DisplayName element is always nobody.

  • ETag

    Child of the Contents or Version element.

    The ETag element specifies the ETag of the applicable item or item version.

    The response body includes ETag elements for the listed folders. However, because they have no content, all folders have the same value for this element.

  • ID

    Child of the Owner element.

    If the item owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the item owner is identified by an AD user account, the value of the ID element is the SID for that account.

    If the item has no owner, the value of the ID element is nobody.

    For folders, the value of the ID element is always nobody.

  • IsLatest

    Child of the Version or DeleteMarker element.

    The IsLatest element indicates whether the item version is the current version of the item. Possible values are:

    • true

      The item version is the current version of the item.

    • false

      The item version is an old version of the item.

  • IsTruncated

    Child of the ListBucketResult or ListVersionsResult element.

    The IsTruncated element indicates whether the returned bucket listing includes the last item that satisfies the request criteria. Possible values are:

    • true

      The returned listing includes the last item that satisfies the request criteria.

    • false

      The returned listing does not include the last item that satisfies the request criteria.

  • Key

    Child of the Contents, Version, or DeleteMarker element.

    The Key element specifies the name of an item or item version in the bucket listing. For a delete marker, the value of the Key element is the name of the object or object version that was deleted.

  • KeyMarker

    Child of the ListVersionsResult element.

    The KeyMarker element specifies the value of the key-marker query parameter included in the request. If the request did not include the key-marker query parameter, the response body includes KeyMarker as an empty element.

  • LastModified

    Child of the Contents, Version, or DeleteMarker element.

    The LastModified element specifies the date and time when the applicable item or item 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:

    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.

  • ListBucketResult

    Root element for a listing of current items.

  • ListVersionsResult

    Root element for a version listing.

  • Marker

    Child of the ListBucketResult element.

    The Marker element specifies the value of the marker query parameter included in the request. If the request did not include the marker query parameter, the response body includes Marker as an empty element.

  • MaxKeys

    Child of the ListBucketResult or ListVersionsResult element.

    The MaxKeys element specifies the value of the max-keys query parameter included in the request. If the request did not include the max-keys query parameter, the value of the MaxKeys element is 1000.

  • Name

    Child of the ListBucketResult or ListVersionsResult element.

    The Name element specifies the name of the applicable bucket.

  • NextMarker

    Child of the ListBucketResult element.

    If the returned listing is truncated, you can use the NextMarker element as the value of the marker query parameter in a new request to retrieve the next set of items that satisfy the request criteria.

    The NextMarker element is returned only if you have specified a delimiter request parameter.

  • NextKeyMarker

    Child of the ListVersionsResult element.

    The NextKeyMarker element specifies the name of the last item included in the returned bucket listing. This element is included in the response body only when the value of the IsTruncated element is true.

    If the returned listing is truncated, you can use the value of the NextKeyMarker element as the value of the key-marker query parameter in a new request to retrieve the next set of items that satisfy the request criteria.

  • NextVersionIdMarker

    Child of the ListVersionsResult element.

    The NextVersionIdMarker element specifies the version ID of the last item included in the returned bucket listing. This element is included in the response body only when the value of the IsTruncated element is true.

    If the returned listing is truncated, you can use the value of the NextVersionIdMarker element as the value of the version-id-marker query parameter in a new request to retrieve the next set of items that satisfy the request criteria.

  • Owner

    Child of the Contents, Version, or DeleteMarker element and container for the DisplayName and ID elements.

    The Owner element identifies the owner of the applicable item.

  • Prefix

    One of these:

    • Child of the ListBucketResult or ListVersionsResult element.

      In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element.

    • Child of the CommonPrefixes element.

      In this case, the Prefix element specifies a common prefix.

  • Size

    Child of the Contents or Version element.

    The Size element specifies the size, in bytes, of the content of the item or item version.

    The response body includes Size elements for the listed folders. However, because folders have no content, the value of this element for a folder is always 0 (zero).

  • StorageClass

    Child of the Contents or Version element.

    The value of the StorageClass element is always STANDARD.

  • Version

    Child of the ListVersionsResult element and container for the elements that describe a version of an item in the bucket.

    The response body contains one Version element for each item version that satisfies the request criteria.

  • VersionId

    Child of the Version or DeleteMarker element.

    The VersionId element specifies the version ID of an item version.

  • VersionIdMarker

    Child of the ListVersionsResult element.

    The VersionIdMarker element specifies the value of the version-id-marker query parameter included in the request. If the request did not include the version-id-marker query parameter, the response body includes VersionIdMarker as an empty element.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to list the contents of a bucket.

CodeMeaningDescription
200OKHCP successfully retrieved the requested bucket listing.
400Bad RequestPossible reasons include that a query parameter has an invalid value.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to list the contents of the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundThe 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: Listing the items in a folder

Here’s a sample GET request for a bucket listing that lists the objects that are in the mktg folder and, separately, the subfolders that are in the mktg folder. The request uses these query parameters:

  • prefix=mktg/

    Lists only items that start with mktg/

  • marker=mktg/

    Starts the listing with the item that follows mktg/ by itself

  • delimiter=/

    Treats items that have a forward slash (/) after mktg/ as having a common prefix

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?prefix=mktg/
     &marker=mktg/&delimiter=/" -H "x-hcp-pretty-print: true"

Request headers

GET /?prefix=mktg/&delimiter=/&marker=mktg/ HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:ysiVYJ/cOr78z69BuDy6fy07ryo=
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"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix>mktg/</Prefix>
     <Marker>mktg/</Marker>
     <MaxKeys>1000</MaxKeys>
     <Delimiter>/</Delimiter>
     <IsTruncated>false</IsTruncated>
     <Contents>
          <Key>mktg/campaign_GoGetEm_expenses.xls</Key>
          <LastModified>2020-02-13T17:44:53.000Z</LastModified>
          <ETag>"6ed7faad1e0661c03ad65a4317d4a94c"</ETag>
          <Size>94328</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
     <Contents>
          <Key>mktg/campaign_LiveIt_expenses.xls</Key>
          <LastModified>2019-12-05T14:32:29.110Z</LastModified>
          <ETag>"7ad452af1e2f61b33a865c4362be5921"</ETag>
          <Size>81578</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
     <CommonPrefixes>
          <Prefix>mktg/budget_proposals/</Prefix>
     </CommonPrefixes>
</ListBucketResult>
Example: Request for the first three items

Here are two sample GET requests for bucket listings that list item versions. The first request returns a list of three items. The second request returns a list of the three items that follow the last item returned by the first request.

The request for the first three items uses these query parameters:

  • versions

    Lists item versions

  • key-marker=mktg/

    Starts the listing with the item that follows mktg/ by itself

  • max-keys=3

    Lists at most three items

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?versions
     &key-marker=mktg/&max-keys=3" -H "x-hcp-pretty-print: true"

Request headers

GET /?versions&key-marker=mktg/&max-keys=3 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:sf4WfS+TzOj9zrHVRA5Z0i1KsFg=
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"?>
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix></Prefix>
     <KeyMarker>mktg/</KeyMarker><VersionIdMarker></VersionIdMarker>
     <NextKeyMarker>mktg/campaign_GoGetEm_expenses.xls</NextKeyMarker>
     <NextVersionIdMarker>87288784288321</NextVersionIdMarker>
     <MaxKeys>3</MaxKeys>
     <IsTruncated>true</IsTruncated>
     <Version>
          <Key>mktg/budget_proposals/</Key>
          <VersionId>87288779571521</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2019-11-13T17:12:00.805Z</LastModified>
          <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
          <Size>0</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>mktg/budget_proposals/BudgProp-2020</Key>
          <VersionId>87288779576769</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2019-11-13T17:12:01.218Z</LastModified>
          <ETag>"af65fc4d3e90617b3ad65a83a946be11"</ETag>
          <Size>124591</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>mktg/campaign_GoGetEm_expenses.xls</Key>
          <VersionId>87288784288321</VersionId>
          <IsLatest>false</IsLatest>
          <LastModified>2020-02-12T20:14:06.519Z</LastModified>
          <ETag>"74d824cd5076a1361da128ee18e5a42b"</ETag>
          <Size>92127</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
</ListVersionsResult>
Example: Request for next three items

The request for the next three items uses these query parameters:

  • versions

    Lists item versions.

  • key-marker=mktg/campaign_GoGetEm_expenses.xls

    version-id-marker=87288784288321

    Starts the listing with the item that follows version 87288784288321 of mktg/campaign_GoGetEm_expenses.xls. The version ID and item name are the values of the NextVersionIdMarker and NextKeyMarker elements from the previous response body, respectively.

  • max-keys=3

    Lists at most three items.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?versions
     &key-marker=mktg/campaign_GoGetEm_expenses.xls
     &version-id-marker=87288784288321&max-keys=3"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?versions&key-marker=mktg/campaign_GoGetEm_expenses.xls
     &version-id-marker=87288784288321&max-keys=3 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Thu, 23 Feb 2017 17:20:01 +0000
Authorization: AWS bGdyZWVu:eYSJshWGcAf7i51jbpl/ZQqqJYM=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Thu, 23 Feb 2017 17:20:01 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix></Prefix>
     <KeyMarker>mktg/campaign_GoGetEm_expenses.xls</KeyMarker>
     <VersionIdMarker>87288784288321</VersionIdMarker>
     <NextKeyMarker>quarterly_rpts/</NextKeyMarker>
     <NextVersionIdMarker>87288727467201</NextVersionIdMarker>
     <MaxKeys>3</MaxKeys>
     <IsTruncated>true</IsTruncated>
     <Version>
          <Key>mktg/campaign_GoGetEm_expenses.xls</Key>
          <VersionId>87288825190337</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2020-02-13T17:44:53.000Z</LastModified>
          <ETag>"6ed7faad1e0661c03ad65a4317d4a94c"</ETag>
          <Size>94328</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>mktg/campaign_LiveIt_expenses.xls</Key>
          <VersionId>87288785222273</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2019-11-5T14:32:29.110Z</LastModified>
          <ETag>"7ad452af1e2f61b33a865c4362be5921"</ETag>
          <Size>81578</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>quarterly_rpts/</Key>
          <VersionId>87288727467201</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2019-07-23T18:26:24.675Z</LastModified>
          <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
          <Size>0</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
</ListVersionsResult>
Example: Listing the versions of an individual object

Here’s a sample GET request for a bucket listing that lists all the versions of the object named AcctgBestPractices.doc and includes one delete marker, indicating that one version was deleted. The request uses these query parameters:

  • versions

    Lists item versions

  • prefix=AcctgBestPractices.doc

    Lists only items that start with AcctgBestPractices.doc

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?versions
     &prefix=AcctgBestPractices.doc" -H "x-hcp-pretty-print: true"

Request headers

GET /?versions&prefix=AcctgBestPractices.doc HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:zkfUJoEb+pOrtVpxxOHeamoD4cI=
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"?>
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix>AcctgBestPractices.doc</Prefix>
     <KeyMarker></KeyMarker>
     <VersionIdMarker></VersionIdMarker>
     <MaxKeys>1000</MaxKeys>
     <IsTruncated>false</IsTruncated>
     <Version>
          <Key>AcctgBestPractices.doc</Key>
          <VersionId>87288758401473</VersionId>
          <IsLatest>false</IsLatest>
          <LastModified>2019-05-29T14:56:05.630Z</LastModified>
          <ETag>"26aa5129552e57fc64e10aa5b3911ee2"</ETag>
          <Size>3206178</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>AcctgBestPractices.doc</Key>
          <VersionId>87288800665537</VersionId>
          <IsLatest>false</IsLatest>
          <LastModified>2019-10-28T19:23:31.305Z</LastModified>
          <ETag>"b7235e841a2cc45a7e42a8a576d493b1"</ETag>
          <Size>3374982</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <Version>
          <Key>AcctgBestPractices.doc</Key>
          <VersionId>87288808614529</VersionId>
          <IsLatest>false</IsLatest>
          <LastModified>2019-12-28T21:06:52.011Z</LastModified>
          <ETag>"5ab7542f753b09fdb73141a66c134b9"</ETag>
          <Size>3557448</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
     <DeleteMarker>
          <Key>AcctgBestPractices.doc</Key>
          <VersionId>87288810855745</VersionId>
          <IsLatest>false</IsLatest>
          <LastModified>2019-12-29T13:10:04.902Z</LastModified>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
     </DeleteMarker>
     <Version>
          <Key>AcctgBestPractices.doc</Key>
          <VersionId>87288815588289</VersionId>
          <IsLatest>true</IsLatest>
          <LastModified>2019-12-29T19:42:16.331Z</LastModified>
          <ETag>"764f38262c6e581f678e1ac9b0211ae8"</ETag>
          <Size>3552369</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Version>
</ListVersionsResult>

Listing bucket contents (version 2)

You use the HTTP GET method to list the contents of a bucket. To list the contents of a bucket, you need browse permission for the bucket. You do not need to be an authenticated user.

For the purpose of a bucket listing, the bucket contents consist not only of the objects you stored in the bucket but also of the folders that you created in the bucket or that HCP created automatically from the object names. For example, by default, if a bucket contains an object named quarterly_rpts/Q4_2019, a list of the bucket contents includes these two items:

  • quarterly_rpts/
  • quarterly_rpts/Q4_2019

By default, a bucket listing includes only the current (or only) versions of objects.

A listing that includes versions of objects may include delete markers. A delete marker indicates that a version of the object was deleted.

A bucket listing is returned in an XML response body. In the response body, items in the bucket listing occur in ascending alphanumeric order by item name. If the listing includes multiple versions of an object, those versions are listed in ascending chronological order by last-modified time.

Request line

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

  • With the bucket name included in the hostname:
    GET /[?[query-parameters]] HTTP/1.1
  • With the bucket name following the hostname:
    GET /bucket-name[?[query-parameters]] HTTP/1.1

query-parameters can be one or more of:

  • continuation-token

    By default, a bucket listing can include at most one thousand items. If your request exceeds this or exceeds the value set for the max-keys query parameter, the response is truncated and you can use the continuation-token query parameter to list the next set of objects. Also, when the IsTruncated response element value is set to true, the response includes the NextContinuationToken element. The value of this element can be used in your next request as the continuation token to list the next set of objects.

    The continuation-token is a value that only the S3 compatible API understands, and objects are listed in UTF-8 character encoding in lexicographical order. If you specify an invalid continuation-token query parameter in a request, a 400 (Bad Request) error is returned, including a message that specifies the invalid continuation-token query parameter.

    The continuation-token parameter name is case sensitive.

  • delimiter

    You use the delimiter query parameter to request a bucket listing that includes a list of common prefixes, where a prefix is the name of an item up through the first occurrence of the character string specified by the delimiter parameter. Each common prefix is listed only once regardless of the number of items with matching names. The items with matching names are not included elsewhere in the listing.

    The returned listing also contains items with names that do not include the character string specified by the delimiter parameter. In the listing, all the named items are listed first, followed by all the common prefixes.

    The items and common prefixes included in a listing are subject to any other criteria specified in the request.

    Both the items and the common prefixes count toward the maximum number of items that can be included in the bucket listing.

    The list of items does not include in-progress multipart uploads. The list of common prefixes does not include common prefixes that are exclusively for multipart uploads.

    The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The delimiter parameter name and the character string you specify are both case sensitive.

  • encoding-type

    You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

    The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

    The encoding-type parameter name is case sensitive.

  • fetch-owner

    You use the fetch-owner query parameter to retrieve owner information. When you specify the fetch-owner query parameter to true, the S3 compatible API returns the owner information in the response.

    The S3 compatible API no longer returns owner information by default in the response. To include owner information in the response, you need to set the fetch-owner query parameter to true.

    The fetch-owner parameter name is case sensitive.

  • list-type

    You use the list-type query parameter in order to use version 2 of the S3 compatible API. The value for this query parameter must always be set to 2 if you want to use version 2 of S3 compatible API requests.

    If any value other than 2 is specified for this query parameter, version 1 of the S3 compatible API is used by default.

    The list-type parameter name is case sensitive.

  • max-keys

    By default, a bucket listing can include at most one thousand items. However, you can use the max-keys query parameter in a bucket listing request to specify a smaller maximum number of items. If more than the maximum number of items satisfy the criteria for a request, you can use query parameters to retrieve the parts in groups.

    Valid values for the max-keys query parameter are integers in the range 0 (zero) through 2,147,483,647. If you specify an integer greater than one thousand, the returned bucket listing includes only the first one thousand items that satisfy the request criteria (or fewer if fewer than one thousand items satisfy the criteria).

    The max-keys parameter name is case sensitive.

  • prefix

    You use the prefix query parameter to request a bucket listing that contains only items with names that begin with a specified character string (the prefix) and, if applicable, common prefixes that begin that prefix.

    The list of items does not include in-progress multipart uploads or common prefixes that are exclusively for multipart uploads.

    The character string you specify for the prefix query parameter can contain any valid UTF-8 characters, including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The prefix parameter name and the character string you specify are both case sensitive.

  • start-after

    You use the start-after query parameter to specify that you want the S3 compatible API to return key names after a specific object key. The start-after query parameter that you specify is always returned in the response, regardless of whether the specified value is valid.

    The start-after query parameter is valid only in the first request. If the response is truncated, you can use the continuation-token query parameter to list the next set of objects. The S3 compatible API lists objects in UTF-8 character encoding in lexicographical order.

    The start-after parameter name and the character string you specify are both case sensitive.

Required headers

The list below describes the headers you can use in a request to list the contents of a bucket.

  • 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
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 list the contents of a bucket.

  • Connection

    Specifies if the connection to the server is open or closed.

  • 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

    Specifies the Internet media type of the response body. For a request to list the contents of a bucket, 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
  • Server

    The version of the HCP system that responded to the request. The value of this header is always HCP followed by the HCP version number (for example, HCP V9.0.0.2).

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

Response body

The list below describes the XML elements in the response body that is returned in response to a request to list the contents of a bucket. The elements are listed in alphabetical order.

  • CommonPrefixes

    Child of the ListBucketResult element and container for the Prefix element.

    The response body contains one CommonPrefixes element for each common prefix in the bucket listing.

  • Contents

    Child of the ListBucketResult element and container for the elements that describe a current item in the bucket.

    The response body contains one Contents element for each item that satisfies the request criteria.

  • ContinuationToken

    Child of the ListBucketResult element.

    If sent with the request, the ContinuationToken element specifies the continuation token for listing the next set of objects.

  • Delimiter

    Child of the ListBucketResult element.

    The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.

  • DisplayName

    Child of the Owner element.

    If the item owner is identified by an HCP user account, the value of the DisplayName element is the user name for that account. If the item owner is identified by an AD user account, the value of the DisplayName element is the user name of that account followed by an at sign (@) and the AD domain name.

    If the item has no owner, the value of the DisplayName element is nobody.

    For folders, the value of the DisplayName element is always nobody.

  • Encoding-Type

    Child of the ListBucketResult element.

    The Encoding-Type element specifies the type of encoding used by the S3 compatible API to encode the key names of objects.

  • ETag

    Child of the Contents element.

    The ETag element specifies the ETag of the applicable item.

    The response body includes ETag elements for the listed folders. However, because they have no content, all folders have the same value for this element.

  • ID

    Child of the Owner element.

    If the item owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the item owner is identified by an AD user account, the value of the ID element is the SID for that account.

    If the item has no owner, the value of the ID element is nobody.

    For folders, the value of the ID element is always nobody.

  • IsTruncated

    Child of the ListBucketResult element.

    The IsTruncated element indicates whether the returned bucket listing includes the last item that satisfies the request criteria. Possible values are:

    • true

      The returned listing includes the last item that satisfies the request criteria.

    • false

      The returned listing does not include the last item that satisfies the request criteria.

  • Key

    Child of the Contents element.

    The Key element specifies the name of an item in the bucket listing.

  • KeyCount

    Child of the ListBucketResult element.

    The KeyCount element specifies the number of keys in the response. The value of the KeyCount element is always less than or equal to the value of the MaxKeys element.

  • LastModified

    Child of the Contents element.

    The LastModified element specifies the date and time when the applicable item 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.

  • ListBucketResult

    Root element for a listing of current items.

  • MaxKeys

    Child of the ListBucketResult element.

    The MaxKeys element specifies the value of the max-keys query parameter included in the request. If the request did not include the max-keys query parameter, the value of the MaxKeys element is 1000.

  • Name

    Child of the ListBucketResult element.

    The Name element specifies the name of the applicable bucket.

  • NextContinuationToken

    Child of the ListBucketResult element.

    If the response is truncated, the NextContinuationToken element is included in the response. The value of this element can be used in your next request as the continuation token to list the next set of objects.

  • Owner

    Child of the Contents element and container for the DisplayName and ID elements.

    The Owner element identifies the owner of the applicable item.

  • Prefix

    One of these:

    • Child of the ListBucketResult element.

      In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element.

    • Child of the CommonPrefixes element.

      In this case, the Prefix element specifies a common prefix.

  • Size

    Child of the Contents element.

    The Size element specifies the size, in bytes, of the content of the item.

    The response body includes Size elements for the listed folders. However, because folders have no content, the value of this element for a folder is always 0 (zero).

  • StartAfter

    Child of the ListBucketResult element.

    If sent with the request, the StartAfter element includes the specific object key after which the S3 compatible API returns key names.

  • StorageClass

    Child of the Contents element.

    The value of the StorageClass element is always STANDARD.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to list the contents of a bucket.

CodeMeaningDescription
200OKHCP successfully retrieved the requested bucket listing.
400Bad RequestPossible reasons include that a query parameter has an invalid value.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to list the contents of the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundThe 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: Listing the items in a folder

Here’s a sample GET request for a bucket listing that lists the objects that are in the mktg folder and, separately, the subfolders that are in the mktg folder. The request uses these query parameters:

  • list-type=2

    Uses version 2 of the S3 compatible API

  • max-keys=1000

    Lists no more than 1000 items in the response

  • prefix=mktg/

    Lists only items that start with mktg/

  • start-after=mktg/

    Starts the listing with the item that follows mktg/ by itself

  • delimiter=/

    Treats items that have a forward slash (/) after mktg/ as having a common prefix

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?list-type=2&max-keys=1000
     &prefix=mktg/&start-after=mktg/&delimiter=/" -H "x-hcp-pretty-print: true"

Request headers

GET /?list-type=2&max-keys=1000&prefix=mktg/&delimiter=/&start-after=mktg/ HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:ysiVYJ/cOr78z69BuDy6fy07ryo=
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
Content-Length: 157
Connection: close
Server: HCP V9.0.0.2
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix>mktg/</Prefix>
     <StartAfter>mktg/</StartAfter>
     <NextContinuationToken>1eGcxW1r/XYCxHnhbY24cK3/Jd36Hy4vZkbM=</NextContinuationToken>
     <KeyCount>1000</KeyCount>
     <MaxKeys>1000</MaxKeys>
     <Delimiter>/</Delimiter>
     <IsTruncated>true</IsTruncated>
     <Contents>
          <Key>mktg/campaign_GoGetEm_expenses.xls</Key>
          <LastModified>2020-02-13T17:44:53.000Z</LastModified>
          <ETag>"6ed7faad1e0661c03ad65a4317d4a94c"</ETag>
          <Size>94328</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
     <Contents>
          <Key>mktg/campaign_LiveIt_expenses.xls</Key>
          <LastModified>2019-12-05T14:32:29.110Z</LastModified>
          <ETag>"7ad452af1e2f61b33a865c4362be5921"</ETag>
          <Size>81578</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
       .
       .
       .
     <CommonPrefixes>
          <Prefix>mktg/budget_proposals/</Prefix>
            .
            .
            .
     </CommonPrefixes>
</ListBucketResult>

Listing the in-progress multipart uploads in a bucket

You use the HTTP GET method with the uploads query parameter to list the multipart uploads that are in progress in a bucket. An in-progress multipart upload is one that has been initiated but not yet completed or aborted. While a multipart upload is in the process of being completed, it is still considered to be in progress.

To list the in-progress multipart uploads in a bucket, you must be an authenticated user. Additionally, you need browse permission for the bucket.

A multipart upload listing is returned in an XML response body. The multipart uploads are listed in ascending alphanumeric order by object name. If the listing includes multiple multipart uploads for the same object, those multipart uploads are listed in ascending chronological order by the time they were initiated.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to list in-progress multipart uploads has either of these formats:

  • With the bucket name included in the hostname:
    GET/?uploads[&query-parameters] HTTP/1.1
  • With the bucket name following the hostname:
    GET/bucket-name?uploads[&query-parameters] HTTP/1.1

The uploads query parameter is case sensitive.

query-parameters can be none, one, or more of:

  • delimiter

    You use the delimiter query parameter to request a multipart upload listing that includes a list of common prefixes for multipart upload object names. A common prefix is the name of an object up through the first occurrence of the character string specified by the delimiter parameter.

    Each common prefix is listed only once regardless of the number of multipart uploads with matching object names. The multipart uploads with object names that begin with the common prefix are not included elsewhere in the listing.

    The returned listing also contains multipart uploads with object names that do not include the character string specified by the delimiter parameter. In the listing, all these multipart uploads are listed first, followed by all the common prefixes.

    The multipart uploads and common prefixes included in a listing are subject to any other criteria specified in the request.

    Both the multipart uploads and the common prefixes count toward the maximum number of multipart uploads that can be included in the listing.

    The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The delimiter parameter name and the character string you specify are both case sensitive.

  • encoding-type

    You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

    The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

    The encoding-type parameter name is case sensitive.

  • key-marker

    You use the key-marker query parameter without the upload-id-marker query parameter to specify a starting point for the returned multipart upload listing. That point is the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.

    For example, the multipart upload listing returned in response to a GET multipart upload listing request with the key-marker=sales/ query parameter contains this multipart upload:

    sales/RulesAndRegulations.pdf

    When more than the requested number of multipart uploads satisfy the criteria in a request for a multipart upload listing, HCP returns a partial listing. In this case, the response body includes:

    • The IsTruncated element with a value of true.
    • The NextKeyMarker element. The value of this element is either the object name for the last multipart upload included in the returned listing or the last common prefix in the returned listing, whichever is alphanumerically greater.
    • Conditionally, the NextUploadIdMarker element.

    To return the next part of the multipart upload listing, you include the key-marker query parameter in another request for the listing. As the parameter value, you specify the value of the NextKeyMarker element returned with the previous partial listing.

    When the returned listing includes the last multipart upload that satisfies the request criteria, the response body includes the IsTruncated element with a value of false and does not include the NextKeyMarker and NextUploadIdMarker elements.

    The character string you specify for the key-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The key-marker parameter name and the character string you specify are both case sensitive.

  • max-uploads

    By default, a multipart upload listing can include at most one thousand multipart uploads. However, you can use the max-uploads query parameter in a multipart upload listing request to specify a smaller maximum number of multipart uploads.

    For example, the bucket listing returned in response to a GET bucket list multipart uploads request with the max-uploads=2 query parameter contains these multipart uploads:

    acctg/AcctgAtExampleCorp-Advanced.mov
    acctg/AcctgAtExampleCorp-Introduction.mov

    If more than the maximum number of multipart uploads satisfy the criteria for a request, you can use the the key-marker and, optionally, upload-id-marker query parameters in conjunction with max-uploads to retrieve the parts in groups.

    Valid values for the max-uploads query parameter are integers in the range 0 (zero) through 1,000. If you specify an integer greater than one thousand, HCP returns a 400 (Invalid Argument) status code and does not return a multipart upload listing.

    The max-uploads parameter name is case sensitive.

  • prefix

    You use the prefix query parameter to request a multipart upload listing that contains only multipart uploads with object names that begin with a specified character string (the prefix).

    For example, the multipart upload listing returned in response to a GET bucket list multipart uploads request with the prefix=acctg query parameter contains only these items:

    acctg/AcctgAtExampleCorp-Advanced.mov
    acctg/AcctgAtExampleCorp-Introduction.mov
    acctg/RulesAndRegulations.pdf

    The character string you specify for the prefix query parameter can contain any valid UTF-8 characters, including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The prefix parameter name and the character string you specify are both case sensitive.

  • upload-id-marker

    By default, if a bucket contains multiple multipart uploads for a given object, a multipart upload listing for the bucket includes all the multipart uploads for that object, where those multipart uploads satisfy the request criteria.

    You use the upload-id-marker query parameter in conjunction with the key-marker parameter to start a multipart upload listing with a multipart upload for which:

    • The object name is the same as the character string specified by the key-marker parameter.
    • The upload ID is the first upload ID for the named object that's alphanumerically greater than the character string specified by the upload-id-marker parameter.

    If no multipart upload satisfies the above criteria, the returned listing starts with the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.

    If the multipart upload listing request includes the upload-id-marker parameter without the key-marker parameter, the upload-id-marker parameter is ignored.

    When the response body for a multipart upload listing request includes the IsTruncated element with a value of true, the response body also includes the NextUploadIdMarker element, except when both of these are true:

    • The response body lists one or more common prefixes.
    • The last multipart upload that satisfies the request criteria does not appear in the response body because the object name for that multipart upload starts with the last listed common prefix.

    The value of the NextUploadIdMarker element, when present, is the upload ID of the last multipart upload included in the returned listing. This is the value to use for the upload-id-marker query parameter in a request to retrieve the next group of multipart uploads that satisfy the request criteria.

    The character string you specify for the upload-id-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

    The upload-id-marker parameter name and the character string you specify are both case sensitive.

Required headers

The list below describes the headers you can use in a request to list in-progress multipart uploads.

  • 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 list in-progress multipart uploads.

  • Content-Type

    Specifies the Internet media type of the response body. For a request to list the parts of a multipart upload, 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.

Response body

The list below describes the XML elements in the response body returned in response to a request to list the multipart uploads that are in progress in a bucket. The elements are listed in alphabetical order.

  • Bucket

    Child of the ListMultipartUploadsResult element.

    The Bucket element specifies the name of the bucket targeted by the request.

  • CommonPrefixes

    Child of the ListMultipartUploadsResult and container for the Prefix element.

    The response body contains one CommonPrefixes element for each common prefix in the multipart upload listing.

  • Delimiter

    Child of the ListMultipartUploadsResult element.

    The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.

  • DisplayName

    Child of the Initiator or Owner element.

    If the initiator or owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the initiator or owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.

  • ID

    Child of the Initiator or Owner element.

    If the initiator or owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the initiator or owner is identified by an AD user account, the value of the ID element is the SID for that account.

  • Initiated

    Child of the Upload element.

    The Initiated element specifies the date and time when the applicable multipart upload was initiated, 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
  • Initiator

    Child of the Upload element and container for the DisplayName and ID elements.

    The Initiator element identifies the user who initiated the applicable multipart upload.

  • IsTruncated

    Child of the ListMultipartUploadsResult element.

    The IsTruncated element indicates whether the returned listing includes the last multipart upload that satisfies the request criteria. Possible values are:

    • true

      The returned listing includes the last multipart upload that satisfies the request criteria.

    • false

      The returned listing does not include the last multipart upload that satisfies the request criteria.

  • Key

    Child of the Upload element.

    The Key element specifies the name of the object to be created by the applicable multipart upload.

  • KeyMarker

    Child of the ListMultipartUploadsResult element.

    The KeyMarker element specifies the value of the key-marker query parameter included in the request. If the request did not include the key-marker query parameter, the response body includes KeyMarker as an empty element.

  • ListMultipartUploadsResult

    Root element.

  • MaxUploads

    Child of the ListMultipartUploadsResult element.

    The MaxUploads element specifies the value of the max-uploads query parameter included in the request. If the request did not include the max-uploads query parameter, the value of the MaxUploads element is 1000.

  • NextKeyMarker

    Child of the ListMultipartUploadsResult element.

    The NextKeyMarker element specifies the object name for the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true.

    If the returned listing is truncated, you can use the value of the NextKeyMarker element as the value of the key-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.

  • NextUploadIdMarker

    Child of the ListMultipartUploadsResult element.

    The NextUploadIdMarker element specifies the upload ID of the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true.

    If the returned listing is truncated, you can use the value of the NextUploadIdMarker element as the value of the upload-id-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.

  • Owner

    Child of the Upload element and container for the DisplayName and ID elements.

    The Owner element identifies the user who will own the object created by the applicable multipart upload.

  • Prefix

    One of these:

    • Child of the ListMultipartUploadsResult.

      In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element.

    • Child of the CommonPrefixes element.

      In this case, the Prefix element specifies a common prefix.

  • StorageClass

    Child of the Upload element.

    The value of the StorageClass element is always STANDARD.

  • Upload

    Child of the ListMultipartUploadsResult and container for the elements that describe a multipart upload.

    The response body contains one Upload element for each multipart upload in the returned listing.

  • UploadId

    Child of the Upload element.

    The UploadId element specifies the upload ID of the applicable multipart upload.

  • UploadIdMarker

    Child of the ListMultipartUploadsResult element.

    The UploadIdMarker element specifies the value of the upload-id-marker query parameter included in the request. If the request did not include the upload-id-marker query parameter, the response body does not include the KeyMarker element.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to list the in-progress multipart uploads in a bucket.

CodeMeaningDescription
200OKHCP successfully retrieved the requested multipart upload listing.
400Bad RequestPossible reasons include that a query parameter has an invalid value.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to list the in-progress multipart uploads in the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundThe 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: Listing the multipart uploads for an object

Here's a sample GET request for a listing of the in-progress multipart uploads in the finance bucket for an object named acctg/RulesAndRegulations.pdf. The request uses the prefix query parameter to specify the object name.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?uploads
             &prefix=acctg/RulesAndRegulations"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?uploads&prefix=acctg/RulesAndRegulations.pdf HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:IUzJmUIE9YYu9S6f7l9iYUqzZRE=
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"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <Prefix>acctg/RulesAndRegulations.pdf</Prefix>
     <MaxUploads>1000</MaxUploads>
     <IsTruncated>false</IsTruncated>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874755807297</UploadId>
          <Initiator>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Initiator>
          <Owner>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>2017-02-22T14:47:39.527Z</Initiated>
     </Upload>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874826378433</UploadId>
          <Initiator>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Initiator>
          <Owner>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>2017-02-22T15:06:02.223Z</Initiated>
     </Upload>
</ListMultipartUploadsResult>
Example: Listing multipart uploads a few at a time

Here's a sample GET request for a limited listing of the in-progress multipart uploads in the finance bucket. The request uses these query parameters in addition to uploads:

  • key-marker=acctg/AcctgAtExampleCorp-Introduction.mov

    Starts the listing with a multipart upload for the first object with a name that's alphanumerically greater than acctg/AcctgAtExampleCorp-Introduction.mov

  • max-uploads=3

    Lists at most three multipart uploads

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k
     "https://finance.europe.hcp.example.com?uploads
          &key-marker=acctg/AcctgAtExampleCorp-Introduction.mov&max-uploads=3"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?uploads&key-marker=acctg/AcctgAtExampleCorp-Introduction.mov
     &max-uploads=3 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:+fE2/Hy6h+ntZ9Q3fuhCnH3SLQM=
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"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <KeyMarker>acctg/AcctgAtExampleCorp-Introduction.mov</KeyMarker>
     <MaxUploads>3</MaxUploads>
     <IsTruncated>false</IsTruncated>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874755807297</UploadId>
          <Initiator>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Initiator>
          <Owner>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>2017-02-22T14:47:39.527Z</Initiated>
     </Upload>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874826378433</UploadId>
          <Initiator>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Initiator>
          <Owner>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>2017-02-22T15:06:02.223Z</Initiated>
     </Upload>
     <Upload>
          <Key>sales/RulesAndRegulations.pdf</Key>
          <UploadId>94874757710913</UploadId>
          <Initiator>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Initiator>
          <Owner>
               <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>2017-02-21T09:48:22.289Z</Initiated>
     </Upload>
</ListMultipartUploadsResult>

Deleting a bucket

You use the HTTP DELETE method to delete a bucket. To delete a bucket, you need to be the bucket owner.

You can delete a bucket only while it’s empty. If you try to delete a bucket that contains any objects, HCP returns a 409 (Conflict) status code and does not delete the bucket.

Request line

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

  • With the bucket name included in the hostname:
    DELETE / HTTP/1.1
  • With the bucket name following the hostname:
    DELETE /bucket-name HTTP/1.1
Required headers

The list below describes the headers you can use in a request to delete a bucket.

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

Response header

The list below describes the header returned in response to a successful request to delete a bucket.

  • 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 delete a bucket.

CodeMeaningDescription
204No ContentHCP successfully deleted the bucket.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You are not the bucket owner.
  • The S3 compatible API is currently disabled for the specified bucket.
  • The tenant does not currently support use of the S3 compatible API for deleting buckets.
404Not FoundThe specified bucket does not exist.
409ConflictThe specified bucket is not empty.
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 a bucket

Here’s a sample DELETE request that deletes the bucket named sales-mktg.

Request with s3curl command line

./s3curl.pl --id=lgreen --delete -- -k "https://sales-mktg.europe.hcp.example.com"

Request headers

DELETE / HTTP/1.1
Host: sales-mktg.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:2nVpI9dSOakB9JZtEyx81RCZTKw=

Response headers

HTTP/1.1 204 No Content
Date: Fri, 07 February 2020 17:19:26 GMT

 

  • Was this article helpful?