对象存储访问控制-SDK 文档-文档中心-腾讯云

简介
本文档提供关于存储桶、对象的访问控制列表（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"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        },
    })
    // 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"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        },
    })
    _, _, 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"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        },
    })
    // 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
赋予指定账户对 Object 的访问权限，具体格式见 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"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        },
    })
    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
授予者所拥有的 Object 的权限，可选值有 READ、READ_ACP、WRITE_ACP、FULL_CONTROL
string
﻿

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

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

参数名称	参数描述	类型	是否必填
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

设置存储桶 ACL

功能说明

方法原型

请求示例

参数说明

查询存储桶 ACL

功能说明

方法原型

请求示例

返回结果说明

对象 ACL

设置对象 ACL

功能说明

方法原型

请求示例

参数说明

查询对象 ACL

功能说明

方法原型

请求示例

参数说明

返回结果说明