HomeStorageObject StorageAPI/CLI
Understanding bucket operations

Jump toUpdate content

Understanding Object Storage bucket operations

Published on 14 September 2018

CreateBucket

This operation allows you to create a new bucket.

Note:

If the operation is successful no output will be returned.

Sample request

PUT / HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Date: Wed, 19 Sep 2018 15:21:16 GMT
Authorization: authorization string

CLI command

aws s3 mb s3://bucketname

DeleteBucket

This operation allows you to delete the bucket mentioned in the command.

Important:

This request will delete your selected bucket. To complete the command, your bucket must be empty.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE / HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170710T181321Z
Authorization: authorization string

CLI command

aws s3api delete-bucket --bucket my-bucket --region fr-par-1

DeleteBucketCors

This operation allows you to delete the CORS configuration of an existing bucket.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE /?cors HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Authorization: authorization string

DeleteBucketLifecycle

This operation deletes the lifecycle cofiguration of a specified bucket.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE /?lifecycle HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Authorization: authorization string

DeleteBucketPolicy

This operation deletes the bucket policy of a specified bucket.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE /my-bucket?policy HTTP/1.1

CLI command

aws s3api delete-bucket-policy --bucket my-bucket

DeleteBucketTagging

This operation allows you to delete the tag set from the specified bucket.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE /?tagging HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Date: Mon, 10 Jun 2018 17:31:43 GMT
Authorization: authorization string

Sample response

HTTP/1.1 204 No Content
Date: Mon, 10 Jun 2018 17:31:45 GMT
Connection: close

DeleteBucketWebsite

This operation deletes the bucket website configuration of a specified bucket.

Note:

If the operation is successful no output will be returned.

Sample request

DELETE /my-bucket?website HTTP/1.1

CLI command

aws s3api delete-bucket-website --bucket my-bucket

GetBucketAcl

This request triggers the display of the Access Control List (ACL) of the bucket BucketName.

Sample request

GET /?acl HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20190411T095616Z
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Thu, 11 Apr 2019 09:56:16 GMT
x-amz-request-id: tx6beab12a75c84071b6378-005caf06c9
Content-Type: application/xml
Content-Length: 698
Connection: close
<?xml version='1.0' encoding='UTF-8'?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<ID>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</ID>
<DisplayName>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
<ID>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</ID>
<DisplayName>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>'

CLI command

aws s3api get-bucket-acl --bucket my-bucket

GetBucketCors

This operation allows you to get the Cross-origin resource sharing (CORS) configuration of a bucket.

Sample request

GET /?cors HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Date: date
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Mon, 18 Mar 2019 10:41:42 GMT
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>Etag</ExposeHeader>
</CORSRule>
</CORSConfiguration>

GetBucketLifecycleConfiguration

This operation returns information about the lifecycle configuration set on the bucket.

Sample request

GET /?lifecycle HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
x-amz-id-2: txda274593e2dc4974a82cc-005cdbe130
x-amz-request-id: txda274593e2dc4974a82cc-005cdbe130
Date: Wed, 15 May 2019 09:51:44 GMT
Content-Length: 238
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ID>ExampleRule</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<Expiration>
<Days>30</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

GetBucketLocation

This operation allows you to display the location constraint of a bucket.

Sample request

GET /?location HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20190411T094149Z
Authorization: authorization string

Sample response

<?xml version='1.0' encoding='UTF-8'?>
<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">nl-ams</LocationConstraint>'

CLI command

aws s3api get-bucket-location --bucket my-bucket

ListObjectVersions

This operation allows you to returns metadata about all of the versions of objects in a bucket.

Sample request

GET /?versions HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20190411T100211Z

Sample response

<?xml version='1.0' encoding='UTF-8'?>
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket-stoic-tesla</Name>
<Prefix/>
<KeyMarker/>
<VersionIdMarker/>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Version>
<Key>holidays.png</Key>
<VersionId>1553680197512368</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2019-03-27T09:49:57.000Z</LastModified>
<ETag>"694be693a6156cd92283c1f29026ac25"</ETag>
<Size>54139</Size>
<Owner>
<ID>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</ID>
<DisplayName>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<Version>
<Key>website.html</Key>
<VersionId>1553680708039023</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2019-03-27T09:58:28.000Z</LastModified>
<ETag>"e5b7e0dcc9d664896cb92a3f7775f352"</ETag>
<Size>138</Size>
<Owner>
<ID>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</ID>
<DisplayName>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

CLI Command

aws s3api list-object-versions --bucket my-bucket

GetBucketPolicy

This operation returns the policy of a specified bucket.

Sample request

GET /my-bucket?policy HTTP/1.1

Sample response:

{
"Policy": "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Action\": [\"s3:GetObject\"], \"Principal\": {\"SCW\": [\"<PROJECT_ID>\"]}, \"Resource\": [\"dst/*\"], \"Effect\": \"Allow\", \"Sid\": \"DelegateGetObject\"}]}"
}

CLI command

aws s3api get-bucket-policy --bucket dst --profile client
{
"Policy": "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Action\": [\"s3:GetObject\"], \"Principal\": {\"SCW\": [\"<PROJECT_ID>\"]}, \"Resource\": [\"dst/*\"], \"Effect\": \"Allow\", \"Sid\": \"DelegateGetObject\"}]}"
}

GetBucketTagging

This operation allows you to the tag set of the specified bucket.

Sample request

GET ?tagging HTTP/1.1
Host: bucket.s3.nl-ams.scw.cloud
Date: Thu, 11 Apr 2019 10:02:11 GMT
Authorization: authorization string
Content-Type: text/plain

Sample response

<Tagging>
<TagSet>
<Tag>
<Key>Bucket Description</Key>
<Value>Holiday Photos</Value>
</Tag>
<Tag>
<Key>Event</Key>
<Value>Paris March 2019</Value>
</Tag>
</TagSet>
</Tagging>

GetBucketVersioning

This operation allows you to return the versioning state of a bucket.

Sample request

GET /?versioning HTTP/1.1
Host: bucket.s3.nl-ams.scw.cloud
Date: Thu, 11 Apr 2019 10:02:11 GMT
Authorization: authorization string
Content-Type: text/plain

Sample response

<VersioningConfiguration xmlns="http://s3.nl-ams.scw.cloud/bucketname/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

CLI command

aws s3api get-bucket-versioning --bucket BucketName

GetBucketWebsite

This operation returns information about the configuration of your bucket website.

Sample request

GET /my-bucket?website HTTP/1.1

CLI command

aws s3api get-bucket-website --bucket <my-bucket>

HeadBucket

This operation can be used to determine if a bucket exists and you have permission to access it.

Note:

If the operation is successful no output will be returned.

Sample request

HEAD / HTTP/1.1
Host: bucket.s3.nl-ams.scw.cloud
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Date: Thu, 11 Apr 2019 10:07:54 GMT
Authorization: authorization string

CLI command

aws s3api head-bucket --bucket BucketName

ListObjects

This operation allows to return some or all (up to 1,000) of the objects in a bucket.

Sample request

GET / HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud

Sample response

HTTP/1.1 200 OK
Content-Length: 526
Content-Type: application/xml
Date: Mon, 20 Apr 2020 08:34:47 GMT
x-amz-id-2: txaef1634de6b6411eb3f9b-005e9d5ea6
x-amz-request-id: txaef1634de6b6411eb3f9b-005e9d5ea6
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucketname</Name>
<Prefix />
<Marker />
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>image.png</Key>
<LastModified>2020-03-25T11:27:33.000Z</LastModified>
<ETag>"2962dcafeea999ebad0e7a09074856e6"</ETag>
<Size>37939</Size>
<Owner>
<ID />
<DisplayName />
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
<Contents>
<Key>file.log</Key>
<LastModified>2020-03-24T21:39:22.000Z</LastModified>
<ETag>"4b5ff0ea81ec9df052ae7947d17ceba1"</ETag>
<Size>137668</Size>
<Owner>
<ID />
<DisplayName />
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
</ListBucketResult>

CLI command

aws s3api list-objects-v2 --bucket my-bucket
Tip:

You can use the request parameters as selection criteria to return a subset of the objects in a bucket. Run aws s3api list-objects-v2 help for more details.

PutBucketAcl

This operation allows you to configure the Access Control List (ACL) of a bucket.

Note:

If the operation is successful no output will be returned.

Sample request

PUT /?acl HTTP/1.1
content-type:application/xml
Host: bucketname.s3.nl-ams.scw.cloud
x-amz-content-sha256: 724483e3830b19d6960345c484fb7904b26e8f2fb34a6c002fa779353b68c8d8
x-amz-date: 20180910T183709Z
Authorization: authorization string
<AccessControlPolicy xmlns="http://s3.nl-ams.scw.cloud/bucketname">
<Owner>
<ID>6174283</ID>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
<ID>04dcf44f-a6ca-4e69-a74c-f0c557d87d79:04dcf44f-a6ca-4e69-a74c-f0c557d87d79</ID>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
<Permission>READ</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

CLI command

aws s3api put-bucket-acl --bucket BucketName --acl private

PutBucketCors

This operation allows you to configure CORS settings of an existing bucket.

Note:

If the operation is successful no output will be returned.

Sample request

PUT /?cors HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Authorization: authorization string
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>Etag</ExposeHeader>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

PutBucketLifecycleConfiguration

Sample request

PUT /?lifecycle HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Content-MD5: e0d656aa8bed46fe766420c6d21537d5
Authorization: authorization string
<LifecycleConfiguration>
<Rule>
<ID>ExampleRule</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<Expiration>
<Days>30</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

Sample response

HTTP/1.1 200 OK

PutBucketTagging

This operation allows you to add a tag set to an existing bucket.

Note:

If the operation is successful no output will be returned.

Sample request

PUT ?tagging HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Content-Length: 1660
x-amz-date: Thu, 14 Mar 2019 10:04:21 GMT
Authorization: authorization string
<Tagging>
<TagSet>
<Tag>
<Key>Bucket Description</Key>
<Value>Holiday Photos</Value>
</Tag>
<Tag>
<Key>Event</Key>
<Value>Paris March 2019</Value>
</Tag>
</TagSet>
</Tagging>

PutBucketVersioning

This operation allows you to set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Sample request

PUT /?versioning HTTP/1.1
Host: bucketname.s3.nl-ams.scw.cloud
Date: Thu, 11 Apr 2019 10:13:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

Sample response

HTTP/1.1 200 OK
x-amz-id-2: tx456e25b3558449a08b406-005caf132c
x-amz-request-id: tx456e25b3558449a08b406-005caf132c
Date: Thu, 11 Apr 2019 10:13:00 GMT

CLI command

aws s3api put-bucket-versioning --bucket BucketName

PutBucketPolicy

This operation applies an S3 bucket policy to an S3 bucket.

Note:

If the operation is successful no output will be returned.

Sample request

PUT /my-bucket?policy HTTP/1.1
{
"Version": "2012-10-17",
"Id": "MyBucketPolicy",
"Statement": [
{
"Sid": "DelegateAccess",
"Effect": "Allow",
"Principal":{
"SCW": "project_id:<PROJECT_ID>"
},
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"<BUCKET_NAME>",
"<BUCKET_NAME>/*"
]
}
]
}

CLI command

Create the file bucket-policy.json with the following content:

{
"Version": "2012-10-17",
"Id": "MyBucketPolicy",
"Statement": [
{
"Sid": "DelegateAccess",
"Effect": "Allow",
"Principal": {
"SCW": "project_id:<PROJECT_ID>"
},
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"<BUCKET_NAME>",
"<BUCKET_NAME>/*"
]
}
]
}

Then, run the command:

aws s3api put-bucket-policy --bucket <BUCKET_NAME> --policy file://bucket-policy.json

PutBucketWebsite

This operation enables bucket website and sets the basic configuration for the website.

PUT /my-bucket?website HTTP/1.1
{
"IndexDocument" : {
"Suffix": "index.html"
},
"ErrorDocument": {
"Key": "error.html"
}
}

To enable bucket website via the CLI, you can create a file called bucket-website.json with the index and error page names.

{
"IndexDocument" : {
"Suffix": "index.html"
},
"ErrorDocument": {
"Key": "error.html"
}
}

And upload it using the following command:

aws s3api put-bucket-website --bucket <BUCKET_NAME> --website-configuration file://bucket-website.json
See Also