Introduction

This document provides an overview of APIs and SDK sample codes related to basic bucket operations and access control lists (ACL).

Basic Operations

ACL

Basic operations

Querying a 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)

Sample request

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

Response description

The result of the request 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 is used to create a bucket under a specified account.

Method prototype

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

Sample request

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 
}

Checking a bucket and its permissions

Feature description

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

Method prototype

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

Sample request

_, 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)

Sample request

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

ACL

Setting a bucket ACL

Feature description

This API is used to set the access control list (ACL) of a specified bucket.

Method prototype

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

Sample request

// 1. Configure the bucket ACL through the 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 the bucket ACL through the 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 a bucket ACL

Feature description

This API is used to query the ACL of a specified bucket.

Method prototype

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

Sample request

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

Response description

The result of the request 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 
}