Understanding bucket operations

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