Actions on Buckets

Introduction

This document provides an overview of APIs and SDK code samples related to basic operations on buckets and bucket access control list (ACL).

Basic Operations

ACL

Basic Operations

Querying the Bucket List

Feature Description

This API is used to query the list of all buckets under a specified account.

Method Prototype

func (s *ServiceService) Get(ctx context.Context) (*ServiceGetResult, *Response, error)

Request Samples

s, _, err := c.Service.Get(context.Background())
if err != nil {
    panic(err)
}

Returned Result

Request result is returned through GetServiceResult.

type ServiceGetResult struct {
    Owner   *Owner  
    'Bucket' => $bucket 
}
type Owner struct {
    ID          string 
    DisplayName string                                              
}
type Bucket struct {
    Name       string
    Region     string
    CreationDate string                                               
} 

Creating a Bucket

Feature Description

This API (PUT Bucket) is used to create a bucket under a specified account.

Method Prototype

func (s *BucketService) Put(ctx context.Context, opt *BucketPutOptions) (*Response, error)

Request Samples

opt := &cos.BucketGetOptions{
    XCosACL: "private",
}
_, err := c.Bucket.Put(context.Background(), nil)
if err != nil {
    panic(err)
}

Parameter Description

type BucketPutOptions struct {
    XCosACL              string 
    XCosGrantRead        string  
    XCosGrantWrite       string  
    XCosGrantFullControl string 
}

Retrieving information on a bucket and its permission

Feature Description

This API is used to verify whether a bucket exists and whether you have the permission to access it.

Method Prototype

func (s *BucketService) Head(ctx context.Context) (*Response, error)

Request Samples

_, err := client.Bucket.Head(context.Background())
if err != nil {
    panic(err)
}

Deleting a bucket

Feature Description

This API is used to delete an empty bucket under a specified account.

Method Prototype

func (s *BucketService) Delete(ctx context.Context) (*Response, error)

Request Samples

_, err := client.Bucket.Delete(context.Background())
if err != nil {
    panic(err)
}

ACL

Configuring bucket ACL

Feature Description

This API (Put Bucket ACL) is used to set an ACL for the specified bucket.

Method Prototype

func (s *BucketService) PutACL(ctx context.Context, opt *BucketPutACLOptions) (*Response, error)

Request Samples

// 1. Configure bucket ACL through request header
opt := &cos.BucketGetOptions{
    Header: &cos.ACLHeaderOptions{
        //private，public-read，public-read-write
        XCosACL: "private",
    },
}
_, err := c.Bucket.Put(context.Background(), nil)
if err != nil {
    panic(err)
}

// 2. Configure bucket ACL through request body
opt := &cos.BucketGetOptions{
    Body: &cos.ACLXml{
        Owner: &cos.Owner{
            "ID": "qcs::cam::uin/100000000001:uin/100000000001",
        },
        AccessControlList: []cos.ACLGrant{
            {
                Grantee: &cos.ACLGrantee{
                    'Type': 'CanonicalUser'|'Group',
                    Type: "RootAccount",
                    "ID": "qcs::cam::uin/100000000001:uin/100000000001",
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
                Permission: "FULL_CONTROL",
            },
        },
    },
}
_, err := c.Bucket.Put(context.Background(), nil)
if err != nil {
    panic(err)
}

Parameter Description

type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}

Querying bucket ACL

Feature Description

This API (Get Bucket ACL) is used to get the ACL of the specified bucket.

Method Prototype

func (s *BucketService) GetACL(ctx context.Context) (*BucketGetACLResult, *Response, error)

Request Samples

_, _, err := client.Bucket.GetACL(context.Background())
if err != nil {
    panic(err)
}

Returned Result

Request result is returned through GetBucketACLResult.

type ACLXml struct {
    Owner             *Owner
    AccessControlList []ACLGrant 
}
type Owner struct { 
    ID          string 
    DisplayName string
}
type ACLGrant struct {
    Grantee    *ACLGrantee
    Permission string
}
type ACLGrantee struct {
    Type        string 
    ID          string 
    DisplayName string
    UIN         string 
}