Understanding bucket operations

Understanding Object Storage bucket operations

Reviewed on 13 June 2023 • 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:

Deleting a bucket will also delete all of its objects. For safety measures, the effective deletion of the bucket will start 24 hours after the deletion request. The bucket name will then be available for other customers to use.

The billing of your resources stops as soon as you send the delete request.

Once you do so, the bucket and all of its objects and versions will no longer be displayed in the console, nor available via the APIs. For this reason, we recommend you erase all objects and versions in the bucket before requesting the deletion, if you wish the bucket deletion to be effective immediately.

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 configuration 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 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\": \"2023-04-17\", \"Statement\": [{\"Action\": [\"s3:GetObject\"], \"Principal\": {\"SCW\": [\"<APPLICATION_ID>\"]}, \"Resource\": [\"dst/*\"], \"Effect\": \"Allow\", \"Sid\": \"DelegateGetObject\"}]}"
}

CLI command

aws s3api get-bucket-policy --bucket dst --profile client
{
    "Policy": "{\"Version\": \"2023-04-17\", \"Statement\": [{\"Action\": [\"s3:GetObject\"], \"Principal\": {\"SCW\": [\"<APPLICATION_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": "22023-04-17",
    "Id": "MyBucketPolicy",
    "Statement": [
        {
            "Sid": "DelegateAccess",
            "Effect": "Allow",
            "Principal":{
                "SCW": "application_id:<APPLICATION_ID>"
            },
            "Action": [
                "s3:ListBucket",
                "s3:GetObject"
            ],
            "Resource": [
                "<BUCKET_NAME>",
                "<BUCKET_NAME>/*"
            ]
        }
    ]
}

CLI command

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

{
    "Version": "2023-04-17",
    "Id": "MyBucketPolicy",
    "Statement": [
        {
            "Sid": "DelegateAccess",
            "Effect": "Allow",
            "Principal": {
                "SCW": "application_id:<APPLICATION_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