Working with buckets

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.

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

• Authorization

  Specifies user credentials or requests anonymous access.

• 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

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

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.

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

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.

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

GET / HTTP/1.1

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

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

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.

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

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.

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

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

• 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

The table below describes HTTP status codes that can be returned in response to a request to check the existence of 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.

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.

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

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

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

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to 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.

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.

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

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.

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

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.

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.

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

• Content-Type

  Specifies the Internet media type of the request body. The only valid values are application/xml and text/xml.

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/">

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.

The table below describes HTTP status codes that can be returned in response to a request to enable or disable versioning for 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.

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.

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

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

The table below describes HTTP status codes that can be returned in response to a request to list the contents of 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.

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.

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.

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

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.

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.

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.

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.

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

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.

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

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