控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

访问控制

最近更新时间:2021-12-14 17:02:38

简介

本文档提供关于存储桶、对象的访问控制列表(ACL)的 API 概览以及 SDK 示例代码。

存储桶 ACL

API 操作名 操作描述
PUT Bucket acl 设置存储桶 ACL 设置指定存储桶的访问权限控制列表(ACL)
GET Bucket acl 查询存储桶 ACL 查询指定存储桶的访问权限控制列表(ACL)

对象 ACL

API 操作名 操作描述
PUT Object acl 设置对象 ACL 设置 Bucket 中某个 Object (文件/对象)的 ACL
GET Object acl 查询对象 ACL 查询 Object(文件/对象)的 ACL

存储桶 ACL

设置存储桶 ACL

功能说明

设置指定存储桶访问权限控制列表(PUT Bucket acl)。

方法原型

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

请求示例

package main

import (
    "context"
    "github.com/tencentyun/cos-go-sdk-v5"
    "net/http"
    "net/url"
    "os"
)

func main() {
    // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
    // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
    u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    client := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            // 通过环境变量获取密钥
            // 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretID: os.Getenv("SECRETID"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })
    // 1. 通过请求头设置 Bucket ACL
    opt := &cos.BucketPutACLOptions{
        Header: &cos.ACLHeaderOptions{
            //private,public-read,public-read-write
            XCosACL: "private",
        },
    }
    _, err := client.Bucket.PutACL(context.Background(), opt)
    if err != nil {
        panic(err)
    }
      // 2. 通过请求体设置 Bucket ACL
    opt = &cos.BucketPutACLOptions{
        Body: &cos.ACLXml{
            Owner: &cos.Owner{
                ID: "qcs::cam::uin/100000000001:uin/100000000001",
            },
            AccessControlList: []cos.ACLGrant{
                {
                    Grantee: &cos.ACLGrantee{
                        // Type 备选项 "Group"、"CanonicalUser"
                        Type: "RootAccount",
                        ID:   "qcs::cam::uin/100000760461:uin/100000760461",
                    },
                    // Permission 备选项 "WRITE"、"FULL_CONTROL"
                    Permission: "FULL_CONTROL",
                },
            },
        },
    }
    _, err = client.Bucket.PutACL(context.Background(), opt)
    if err != nil {
        panic(err)
    }
}

参数说明

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

参数名称 参数描述 类型 是否必填
XCosACL 设置 Bucket 的 ACL,如 private,public-read,public-read-write string
XCosGrantFullControl 赋予指定账户对 Bucket 的读写权限。格式为id=" ",id=" "。当需要给子账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}",当需要给主账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}"。例如id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" string
XCosGrantRead 赋予指定账户对 Bucket 的读权限。格式为id=" ",id=" "。当需要给子账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}",当需要给主账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}"。例如id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" string
XCosGrantWrite 赋予指定账户对 Bucket 的写权限。格式为id=" ",id=" "。当需要给子账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}",当需要给主账户授权时,格式为id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}"。例如id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" string
ACLXML 赋予指定账户对 Bucket 的访问权限,具体格式见 GET Bucket acl 返回结果说明 struct

查询存储桶 ACL

功能说明

查询指定存储桶的访问权限控制列表(GET Bucket acl)。

方法原型

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

请求示例

package main

import (
    "context"
    "github.com/tencentyun/cos-go-sdk-v5"
    "net/http"
    "net/url"
    "os"
)

func main() {
    // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
    // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
    u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    client := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            // 通过环境变量获取密钥
            // 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretID: os.Getenv("SECRETID"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })
    _, _, err := client.Bucket.GetACL(context.Background())
    if err != nil {
        panic(err)
    }
}

返回结果说明

通过 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
    URI         string 
}

参数名称 参数描述 类型
Owner Bucket 拥有者的信息,包括 DisplayName 和 ID struct
AccessControlList Bucket 权限授予者的信息,包括 Grantee和 Permission struct
Grantee 权限授予者的信息,包括 DisplayName,Type,ID 和 URI struct
Type 权限授予者的类型,类型为 CanonicalUser 或者 Group string
ID Type 为 CanonicalUser 时,对应权限授予者的 ID,格式为 qcs::cam::uin/[OwnerUin]:uin/[OwnerUin],如 qcs::cam::uin/100000000001:uin/100000000001, 当 Type 指定为 CanonicalUser 时 ID 必选 string
DisplayName 权限被授予者的名称,可以不填,或者和ID的值保持一致 string
URI Type 为 Group 时,填入预设用户组的 URI,例如 http://cam.qcloud.com/groups/global/AllUsers, 详情请参见 ACL 概述 string
Permission 授予者所拥有的 Bucket 的权限,可选值有 FULL_CONTROL,WRITE,READ,分别对应读写权限、写权限、读权限 string

对象 ACL

设置对象 ACL

功能说明

设置对象访问权限控制列表(PUT Object acl)。

方法原型

func (s *ObjectService) PutACL(ctx context.Context, key string, opt *ObjectPutACLOptions) (*Response, error)

请求示例

package main

import (
    "context"
    "github.com/tencentyun/cos-go-sdk-v5"
    "net/http"
    "net/url"
    "os"
)

func main() {
    // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
    // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
    u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    client := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            // 通过环境变量获取密钥
            // 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretID: os.Getenv("SECRETID"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })
    // 1.通过请求头设置
    opt := &cos.ObjectPutACLOptions{
        Header: &cos.ACLHeaderOptions{
            XCosACL: "private",
        },
    }
    key := "exampleobject"
    _, err := client.Object.PutACL(context.Background(), key, opt)
    if err != nil {
        panic(err)
    }
    // 2.通过请求体设置
    opt = &cos.ObjectPutACLOptions{
        Body: &cos.ACLXml{
            Owner: &cos.Owner{
                ID: "qcs::cam::uin/100000000001:uin/100000000001",
            },
            AccessControlList: []cos.ACLGrant{
                {
                    Grantee: &cos.ACLGrantee{
                        Type: "RootAccount",
                        ID:   "qcs::cam::uin/100000760461:uin/100000760461",
                    },

                    Permission: "FULL_CONTROL",
                },
            },
        },
    }
    _, err = client.Object.PutACL(context.Background(), key, opt)
    if err != nil {
        panic(err)
    }
}

参数说明

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

参数名称 参数描述 类型 是否必填
key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg string
XCosACL 设置 Object 的 ACL,如 private,public-read string
XCosGrantFullControl 赋予被授权者所有的权限。格式:id="[OwnerUin]" string
XCosGrantRead 赋予被授权者读的权限。格式:id="[OwnerUin]" string
ACLXML 赋予指定账户对 Bucket 的访问权限,具体格式见 get object acl 返回结果说明 struct

查询对象 ACL

功能说明

查询 Object(文件/对象)的 ACL(GET Object acl)。

方法原型

func (s *ObjectService) GetACL(ctx context.Context, key string) (*ObjectGetACLResult, *Response, error)

请求示例

package main

import (
    "context"
    "github.com/tencentyun/cos-go-sdk-v5"
    "net/http"
    "net/url"
    "os"
)

func main() {
    // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
    // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
    u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    client := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            // 通过环境变量获取密钥
            // 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretID: os.Getenv("SECRETID"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })
    key := "exampleobject"
    _, _, err := client.Object.GetACL(context.Background(), key)
    if err != nil {
        panic(err)
    }
}

参数说明

参数名称 参数描述 类型 是否必填
key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg string

返回结果说明

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
    URI         string 
}

参数名称 参数描述 类型
Owner Bucket 拥有者的信息,包括 DisplayName 和 ID struct
AccessControlList Bucket 权限授予者的信息,包括 Grantee和 Permission struct
Grantee 权限授予者的信息,包括 DisplayName,Type,ID 和 URI struct
Type 权限授予者的类型,类型为 CanonicalUser 或者 Group string
ID Type 为 CanonicalUser 时,对应权限授予者的 ID,格式为 qcs::cam::uin/[OwnerUin]:uin/[OwnerUin],如 qcs::cam::uin/100000000001:uin/100000000001, 当 Type 指定为 CanonicalUser 时 ID 必选 string
DisplayName 权限被授予者的名称,可以不填,或者和ID的值保持一致 string
URI Type 为 Group 时,填入预设用户组的 URI,例如 http://cam.qcloud.com/groups/global/AllUsers, 详情请参见 ACL 概述 string
Permission 授予者所拥有的 Bucket 的权限,可选值有 FULL_CONTROL,WRITE,READ,分别对应读写权限、写权限、读权限 string
目录