Creates a new bucket. To create a bucket, you must have a user ID and a valid AWS Access Key ID to authenticate requests. You may not create buckets as an anonymous user.
Note
We do not support request entities for PUT /{bucket} in this release.
In general, bucket names should follow domain name constraints.
PUT /{bucket} HTTP/1.1
Host: cname.domain.com
x-amz-acl: public-read-write
Authorization: AWS {access-key}:{hash-of-header-and-secret}
Name | Description | Valid Values | Required |
---|---|---|---|
x-amz-acl | Canned ACLs. | private, public-read, public-read-write, authenticated-read | No |
If the bucket name is unique, within constraints and unused, the operation will succeed. If a bucket with the same name already exists and the user is the bucket owner, the operation will succeed. If the bucket name is already in use, the operation will fail.
HTTP Status | Status Code | Description |
---|---|---|
409 | BucketAlreadyExists | Bucket already exists under different user’s ownership. |
Deletes a bucket. You can reuse bucket names following a successful bucket removal.
DELETE /{bucket} HTTP/1.1
Host: cname.domain.com
Authorization: AWS {access-key}:{hash-of-header-and-secret}
HTTP Status | Status Code | Description |
---|---|---|
204 | No Content | Bucket removed. |
Returns a list of bucket objects.
GET /{bucket}?max-keys=25 HTTP/1.1
Host: cname.domain.com
Name | Type | Description |
---|---|---|
prefix | String | Only returns objects that contain the specified prefix. |
delimiter | String | The delimiter between the prefix and the rest of the object name. |
marker | String | A beginning index for the list of objects returned. |
max-keys | Integer | The maximum number of keys to return. Default is 1000. |
HTTP Status | Status Code | Description |
---|---|---|
200 | OK | Buckets retrieved |
GET /{bucket} returns a container for buckets with the following fields.
Name | Type | Description |
---|---|---|
ListBucketResult | Entity | The container for the list of objects. |
Name | String | The name of the bucket whose contents will be returned. |
Prefix | String | A prefix for the object keys. |
Marker | String | A beginning index for the list of objects returned. |
MaxKeys | Integer | The maximum number of keys returned. |
Delimiter | String | If set, objects with the same prefix will appear in the CommonPrefixes list. |
IsTruncated | Boolean | If true, only a subset of the bucket’s contents were returned. |
CommonPrefixes | Container | If multiple objects contain the same prefix, they will appear in this list. |
The ListBucketResult contains objects, where each object is within a Contents container.
Name | Type | Description |
---|---|---|
Contents | Object | A container for the object. |
Key | String | The object’s key. |
LastModified | Date | The object’s last-modified date/time. |
ETag | String | An MD-5 hash of the object. (entity tag) |
Size | Integer | The object’s size. |
StorageClass | String | Should always return STANDARD. |
Retrieves the bucket access control list. The user needs to be the bucket owner or to have been granted READ_ACP permission on the bucket.
Add the acl subresource to the bucket request as shown below.
GET /{bucket}?acl HTTP/1.1
Host: cname.domain.com
Authorization: AWS {access-key}:{hash-of-header-and-secret}
Name | Type | Description |
---|---|---|
AccessControlPolicy | Container | A container for the response. |
AccessControlList | Container | A container for the ACL information. |
Owner | Container | A container for the bucket owner’s ID and DisplayName. |
ID | String | The bucket owner’s ID. |
DisplayName | String | The bucket owner’s display name. |
Grant | Container | A container for Grantee and Permission. |
Grantee | Container | A container for the DisplayName and ID of the user receiving a grant of permission. |
Permission | String | The permission given to the Grantee bucket. |
Sets an access control to an existing bucket. The user needs to be the bucket owner or to have been granted WRITE_ACP permission on the bucket.
Name | Type | Description |
---|---|---|
AccessControlPolicy | Container | A container for the request. |
AccessControlList | Container | A container for the ACL information. |
Owner | Container | A container for the bucket owner’s ID and DisplayName. |
ID | String | The bucket owner’s ID. |
DisplayName | String | The bucket owner’s display name. |
Grant | Container | A container for Grantee and Permission. |
Grantee | Container | A container for the DisplayName and ID of the user receiving a grant of permission. |
Permission | String | The permission given to the Grantee bucket. |
GET /?uploads returns a list of the current in-progress multipart uploads–i.e., the application initiates a multipart upload, but the service hasn’t completed all the uploads yet.
GET /{bucket}?uploads HTTP/1.1
You may specify parameters for GET /{bucket}?uploads, but none of them are required.
Name | Type | Description |
---|---|---|
prefix | String | Returns in-progress uploads whose keys contains the specified prefix. |
delimiter | String | The delimiter between the prefix and the rest of the object name. |
key-marker | String | The beginning marker for the list of uploads. |
max-keys | Integer | The maximum number of in-progress uploads. The default is 1000. |
max-uploads | Integer | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. |
upload-id-marker | String | Ignored if key-marker isn’t specified. Specifies the ID of first upload to list in lexicographical order at or following the ID. |
Name | Type | Description |
---|---|---|
ListMultipartUploadsResult | Container | A container for the results. |
ListMultipartUploadsResult.Prefix | String | The prefix specified by the prefix request parameter (if any). |
Bucket | String | The bucket that will receive the bucket contents. |
KeyMarker | String | The key marker specified by the key-marker request parameter (if any). |
UploadIdMarker | String | The marker specified by the upload-id-marker request parameter (if any). |
NextKeyMarker | String | The key marker to use in a subsequent request if IsTruncated is true. |
NextUploadIdMarker | String | The upload ID marker to use in a subsequent request if IsTruncated is true. |
MaxUploads | Integer | The max uploads specified by the max-uploads request parameter. |
Delimiter | String | If set, objects with the same prefix will appear in the CommonPrefixes list. |
IsTruncated | Boolean | If true, only a subset of the bucket’s upload contents were returned. |
Upload | Container | A container for Key, UploadId, InitiatorOwner, StorageClass, and Initiated elements. |
Key | String | The key of the object once the multipart upload is complete. |
UploadId | String | The ID that identifies the multipart upload. |
Initiator | Container | Contains the ID and DisplayName of the user who initiated the upload. |
DisplayName | String | The initiator’s display name. |
ID | String | The initiator’s ID. |
Owner | Container | A container for the ID and DisplayName of the user who owns the uploaded object. |
StorageClass | String | The method used to store the resulting object. STANDARD or REDUCED_REDUNDANCY |
Initiated | Date | The date and time the user initiated the upload. |
CommonPrefixes | Container | If multiple objects contain the same prefix, they will appear in this list. |
CommonPrefixes.Prefix | String | The substring of the key after the prefix as defined by the prefix request parameter. |