访问控制

最后更新时间:2021-05-12 11:40:59

    简介

    本文档提供关于存储桶、对象的访问控制列表(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)
    

    请求示例

    // 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)
    

    请求示例

    _, _, 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
        UIN         string 
    }
    
    参数名称 参数描述 类型
    Owner Bucket 拥有者的信息,包括 DisplayName 和 ID struct
    AccessControlList Bucket 权限授予者的信息,包括 Grantee和 Permission struct
    Grantee 权限授予者的信息,包括 DisplayName,Type,ID 和 UIN struct
    Type 权限授予者的类型,类型为 CanonicalUser 或者 Group string
    ID Type 为 CanonicalUser 时,对应权限授予者的 ID string
    DisplayName 权限授予者的名字 string
    UIN Type 为 Group 时,对应权限授予者的 UIN 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)
    

    请求示例

    // 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)
    

    请求示例

    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
        UIN         string 
    }
    
    参数名称 参数描述 类型
    Owner Bucket 拥有者的信息,包括 DisplayName 和 ID struct
    AccessControlList Bucket 权限授予者的信息,包括 Grantee 和 Permission struct
    Grantee 权限授予者的信息,包括 DisplayName,Type,ID 和 UIN struct
    Type 权限授予者的类型,类型为 CanonicalUser 或者 Group string
    ID Type 为 CanonicalUser 时,对应权限授予者的 ID string
    DisplayName 权限授予者的名字 string
    UIN Type 为 Group 时,对应权限授予者的 UIN string
    Permission 授予者所拥有的 Bucket 的权限,可选值有 FULL_CONTROL,WRITE,READ,分别对应读写权限、写权限、读权限 string