Retrieving the ACL for a bucket
ou use the HTTP GET method with the acl query parameter to retrieve the ACL for a bucket. To retrieve the ACL for a bucket, you need 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 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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-amz-date
header.Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the
Date
header above.
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
andfalse
are not case sensitive.
Response headers
The list below 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 table below describes HTTP status codes that can be returned in response to a request to retrieve a bucket ACL.
Code | Meaning | Description |
200 | OK | HCP successfully retrieved the bucket ACL. |
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | The specified bucket does not exist. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service Unavailable |
HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator. |
Example: Retrieving a bucket ACL
Here’s 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>