租户端存储对象存储（CSP） SDK文档

接口文档

最近更新时间: 2024-12-19 17:12:00

存储桶操作

简介

本文档提供关于存储桶的基本操作和访问控制列表（ACL）的相关 API 概览以及 SDK 示例代码。

基本操作

API	操作名	操作描述
PUT Bucket	创建存储桶	在指定账号下创建一个存储桶
HEAD Bucket	检索存储桶及其权限	检索存储桶是否存在且是否有权限访问
DELETE Bucket	删除存储桶	删除指定账号下的空存储桶

访问控制列表

API	操作名	操作描述
PUT Bucket acl	设置存储桶 ACL	设置存储桶的 ACL 配置
GET Bucket acl	查询存储桶 ACL	查询存储桶的 ACL 配置

基本操作

创建存储桶

功能说明

在指定账号下创建一个存储桶。

方法原型

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

请求示例

opt := &cos.BucketPutOptions{
    XCosACL: "public-read",
}
resp, err := client.Bucket.Put(context.Background(), opt)

参数说明

type BucketPutOptions struct {
    XCosACL              string 
    XCosGrantRead        string  
    XCosGrantWrite       string  
    XCosGrantFullControl string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">XCosACL</td><td class="">设置 Bucket 的 ACL，如 private，public-read，public-read-write</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantWrite</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr></tbody></table>




### 检索存储桶及其权限


#### 功能说明

检索存储桶是否存在且是否有权限访问。




#### 方法原型

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

请求示例

resp, err := client.Bucket.Head(context.Background())

删除存储桶

功能说明

删除指定账号下的空存储桶。

方法原型

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

请求示例

resp, err := client.Bucket.Delete(context.Background())

访问控制列表

设置存储桶 ACL

功能说明

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

方法原型

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

请求示例

// 1. Set Bucket ACL by header.
opt := &cos.BucketPutACLOptions{
    Header: &cos.ACLHeaderOptions{
        //private，public-read，public-read-write
        XCosACL: "private",
    },
}
resp, err := client.Bucket.PutACL(context.Background(), opt)

// 2. Set Bucket ACL by body.
opt = &cos.BucketPutACLOptions{
    Body: &cos.ACLXml{
        Owner: &cos.Owner{
            ID: "qcs::cam::uin/100000760461:uin/100000760461",
        },
        AccessControlList: []cos.ACLGrant{
            {
                Grantee: &cos.ACLGrantee{
                    Type: "RootAccount",
                    ID:"qcs::cam::uin/100000760461:uin/100000760461",
                },
                Permission: "FULL_CONTROL",
            },
        },
    },
}
resp, err := client.Bucket.PutACL(context.Background(), opt)

参数说明

type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">XCosACL</td><td class="">设置 Bucket 的 ACL，如 private，public-read，public-read-write</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantWrite</td><td class="">赋予指定账户对 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"`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ACLXML</td><td class="">赋予指定账户对 Bucket 的访问权限，具体格式见 GET Bucket acl 返回结果说明</td><td class="">struct</td><td class="">否</td></tr></tbody></table>




### 查询存储桶 ACL


#### 功能说明

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




#### 方法原型

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

请求示例

v, resp, err := client.Bucket.GetACL(context.Background())

返回结果说明

通过 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 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Owner</td><td class="">Bucket 拥有者的信息，包括 DisplayName 和 ID</td><td class="">struct</td></tr><tr><td class="">AccessControlList</td><td class="">Bucket 权限授予者的信息，包括 Grantee和 Permission</td><td class="">struct</td></tr><tr><td class="">Grantee</td><td class="">权限授予者的信息，包括 DisplayName，Type，ID 和 UIN</td><td class="">struct</td></tr><tr><td class="">Type</td><td class="">权限授予者的类型，类型为 CanonicalUser 或者 Group</td><td class="">string</td></tr><tr><td class="">ID</td><td class="">Type 为 CanonicalUser 时，对应权限授予者的 ID</td><td class="">string</td></tr><tr><td class="">DisplayName</td><td class="">权限授予者的名字</td><td class="">string</td></tr><tr><td class="">UIN</td><td class="">Type 为 Group 时，对应权限授予者的 UIN</td><td class="">string</td></tr><tr><td class="">Permission</td><td class="">授予者所拥有的 Bucket 的权限，可选值有 FULL_CONTROL，WRITE，READ，分别对应读写权限、写权限、读权限</td><td class="">string</td></tr></tbody></table>


# 对象操作


## 简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。



**简单操作**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">GET Bucket（List Object）</td><td class="">查询对象列表</td><td class="">查询存储桶下的部分或者全部对象</td></tr><tr><td class="">PUT Object</td><td class="">简单上传对象</td><td class="">上传一个 Object（文件/对象）至 Bucket</td></tr><tr><td class="">HEAD Object</td><td class="">查询对象元数据</td><td class="">查询 Object 的 Meta 信息</td></tr><tr><td class="">GET Object</td><td class="">下载对象</td><td class="">下载一个 Object（文件/对象）至本地</td></tr><tr><td class="">PUT Object - Copy</td><td class="">设置对象复制</td><td class="">复制文件到目标路径</td></tr><tr><td class="">DELETE Object</td><td class="">删除单个对象</td><td class="">在 Bucket 中删除指定 Object （文件/对象）</td></tr><tr><td class="">DELETE Multiple Object</td><td class="">删除多个对象</td><td class="">在 Bucket 中批量删除 Object （文件/对象）</td></tr></tbody></table>

**分块操作**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">List Multipart Uploads</td><td class="">查询分块上传</td><td class="">查询正在进行中的分块上传信息</td></tr><tr><td class="">Initiate Multipart Upload</td><td class="">初始化分块上传</td><td class="">初始化 Multipart Upload 上传操作</td></tr><tr><td class="">Upload Part</td><td class="">上传分块</td><td class="">分块上传文件</td></tr><tr><td class="">List Parts</td><td class="">查询已上传块</td><td class="">查询特定分块上传操作中的已上传的块</td></tr><tr><td class="">Complete Multipart Upload</td><td class="">完成分块上传</td><td class="">完成整个文件的分块上传</td></tr><tr><td class="">Abort Multipart Upload</td><td class="">终止分块上传</td><td class="">终止一个分块上传操作并删除已上传的块</td></tr></tbody></table>

**其他操作**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">PUT Object acl</td><td class="">设置对象 ACL</td><td class="">设置 Bucket 中某个 Object （文件/对象）的 ACL</td></tr><tr><td class="">GET Object acl</td><td class="">查询对象 ACL</td><td class="">查询 Object（文件/对象）的 ACL</td></tr></tbody></table>


## 简单操作


### 查询对象列表


#### 功能说明

查询存储桶下的部分或者全部对象。




#### 方法原型

``` go
func (s *BucketService) Get(ctx context.Context, opt *BucketGetOptions) (*BucketGetResult, *Response, error)

请求示例

opt := &cos.BucketGetOptions{
    Prefix: "test",
    MaxKeys: 100,                                
}
v, resp, err := client.Bucket.Get(context.Background(), opt)

参数说明

type BucketGetOptions struct {
    Prefix       string 
    Delimiter    string 
    EncodingType string 
    Marker       string 
    MaxKeys      int    
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">Prefix</td><td class="">默认为空，对对象键进行筛选，匹配前缀 prefix 为相同值的 objects</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Delimiter</td><td class="">默认为空，如需模拟文件夹，可设置分隔符`/`</td><td class="">string</td><td class="">否</td></tr><tr><td class="">EncodingType</td><td class="">默认不编码，规定返回值的编码方式，可选值：url</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Marker</td><td class="">默认以 UTF-8 二进制顺序列出条目，标记返回 objects 的 list 的起点位置</td><td class="">string</td><td class="">否</td></tr><tr><td class="">MaxKeys</td><td class="">最多返回的 objects 数量，默认为最大的1000</td><td class="">int</td><td class="">否</td></tr></tbody></table>


#### 返回结果说明

``` go
type BucketGetResult struct {
    Name           string
    Prefix         string 
    Marker         string 
    NextMarker     string 
    Delimiter      string 
    MaxKeys        int
    IsTruncated    bool
    Contents       []Object 
    CommonPrefixes []string 
    EncodingType   string   
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Name</td><td class="">存储桶名称，格式：BucketName-APPID，例如 examplebucket-1250000000</td><td class="">string</td></tr><tr><td class="">Prefix</td><td class="">默认为空，对对象键进行筛选，匹配前缀 prefix 为相同值的 objects</td><td class="">string</td></tr><tr><td class="">Marker</td><td class="">默认以 UTF-8 二进制顺序列出条目，标记返回 objects 的 list 的起点位置</td><td class="">string</td></tr><tr><td class="">NextMarker</td><td class="">当 IsTruncated 为 true 时，标记下一次返回 objects 的 list 的起点位置</td><td class="">string</td></tr><tr><td class="">Delimiter</td><td class="">默认为空，如需模拟文件夹，可设置分隔符`/ `</td><td class="">string</td></tr><tr><td class="">MaxKeys</td><td class="">最多返回的 objects 数量，默认为最大的1000</td><td class="">int</td></tr><tr><td class="">IsTruncated</td><td class="">表示返回的 objects 是否被截断</td><td class="">bool</td></tr><tr><td class="">Contents</td><td class="">包含所有 object 元信息的 list，每个 Object 类型包括 ETag，StorageClass，Key，Owner，LastModified，Size 等信息</td><td class="">[]Object</td></tr><tr><td class="">CommonPrefixes</td><td class="">所有以 Prefix 开头，以 Delimiter 结尾的 Key 被归到同一类</td><td class="">[]string</td></tr><tr><td class="">EncodingType</td><td class="">默认不编码，规定返回值的编码方式，可选值：url</td><td class="">string</td></tr></tbody></table>




### 简单上传对象


#### 功能说明

上传一个 Object（文件/对象）至存储桶（PUT Object）。




#### 方法原型

``` go
func (s *ObjectService) Put(ctx context.Context, key string, r io.Reader, opt *ObjectPutOptions) (*Response, error)

请求示例

key := "put_option.go"
f, err := os.Open("./test")
opt := &cos.ObjectPutOptions{
    ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
        ContentType: "text/html",
    },
    ACLHeaderOptions: &cos.ACLHeaderOptions{
        XCosACL: "private",
    },
}
resp, err = client.Object.Put(context.Background(), key, f, opt)

type ObjectPutOptions struct {
    *ACLHeaderOptions       
    *ObjectPutHeaderOptions 
}
type ACLHeaderOptions struct {
    XCosACL              string                           
    XCosGrantRead        string
    XCosGrantWrite       string 
    XCosGrantFullControl string                                           
} 
type ObjectPutHeaderOptions struct {
    CacheControl       string 
    ContentDisposition string 
    ContentEncoding    string 
    ContentType        string 
    ContentLength      int   
    Expires            string 
    // 自定义的 x-cos-meta-* header
    XCosMetaXXX        *http.Header 
    XCosStorageClass   string      
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">r</td><td class="">上传文件的内容，可以为文件流或字节流，当 r 不是`bytes.Buffer/bytes.Reader/strings.Reader`时，必须指定`opt.ObjectPutHeaderOptions.ContentLength`</td><td class="">io.Reader</td><td class="">是</td></tr><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">XCosACL</td><td class="">设置文件的 ACL，如 private，public-read，public-read-write</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予被授权者所有的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予被授权者读的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosStorageClass</td><td class="">设置文件的存储类型，默认值：STANDARD</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Expires</td><td class="">设置 Content-Expires</td><td class="">string</td><td class="">否</td></tr><tr><td class="">CacheControl</td><td class="">缓存策略，设置 Cache-Control</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentType</td><td class="">内容类型，设置 Content-Type</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentDisposition</td><td class="">文件名称，设置 Content-Disposition</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentEncoding</td><td class="">编码格式，设置 Content-Encoding</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentLength</td><td class="">设置传输长度</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosMetaXXX</td><td class="">用户自定义的文件元信息， 必须以 x-cos-meta 开头，否则会被忽略</td><td class="">http.Header</td><td class="">否</td></tr></tbody></table>


#### 返回结果说明

``` go
{
    'ETag': 'string',
    'x-cos-expiration': 'string'
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">ETag</td><td class="">上传文件的 MD5 值</td><td class="">string</td></tr><tr><td class="">x-cos-expiration</td><td class="">设置生命周期后，返回文件过期规则</td><td class="">string</td></tr></tbody></table>


### 查询对象元数据


#### 功能说明

查询 Object 的 Meta 信息（HEAD Object）。




#### 方法原型

``` go
func (s *ObjectService) Head(ctx context.Context, key string, opt *ObjectHeadOptions) (*Response, error)

请求示例

key := "test/hello.txt"
resp, err := client.Object.Head(context.Background(), key, nil)

参数说明

type ObjectHeadOptions struct {
    IfModifiedSince string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">IfModifiedSince</td><td class="">在指定时间后被修改才返回</td><td class="">string</td><td class="">否</td></tr></tbody></table>


#### 返回结果说明

``` go
{
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'X-Cos-Request-Id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">文件元信息</td><td class="">获取文件的元信息，包括 Etag 和 X-Cos-Request-Id 等信息，也会包含设置的文件元信息</td><td class="">string</td></tr></tbody></table>


### 下载对象


#### 功能说明

下载一个 Object（文件/对象）至本地（GET Object）。




#### 方法原型

``` go
func (s *ObjectService) Get(ctx context.Context, key string, opt *ObjectGetOptions) (*Response, error)

func (s *ObjectService) GetToFile(ctx context.Context, key, localfile string, opt *ObjectGetOptions) (*Response, error)

请求示例

key := "test/hello.txt"
opt := &cos.ObjectGetOptions{
    ResponseContentType: "text/html",
    Range:               "bytes=0-3",
}
// opt 可选，无特殊设置可设为 nil
// 1. Get object by resp body.
resp, err := client.Object.Get(context.Background(), key, opt)
bs, _ = ioutil.ReadAll(resp.Body)
resp.Body.Close()
fmt.Printf("%s\n", string(bs))

// 2.Get object to local file.
_, err = c.Object.GetToFile(context.Background(), name, "hello_1.txt", nil)
if err != nil {
    panic(err)
}

参数说明

type ObjectGetOptions struct {
    ResponseContentType        string 
    ResponseContentLanguage    string 
    ResponseExpires            string 
    ResponseCacheControl       string 
    ResponseContentDisposition string 
    ResponseContentEncoding    string 
    Range                      string 
    IfModifiedSince            string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">localfile</td><td class="">设置响应头部 Content-Type</td><td class="">string</td><td class="">是</td></tr><tr><td class="">ResponseContentType</td><td class="">设置响应头部 Content-Type</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ResponseContentLanguage</td><td class="">设置响应头部 Content-Language</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ResponseExpires</td><td class="">设置响应头部 Content-Expires</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ResponseCacheControl</td><td class="">设置响应头部 Cache-Control</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ResponseContentDisposition</td><td class="">设置响应头部 Content-Disposition</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ResponseContentEncoding</td><td class="">设置响应头部 Content-Encoding</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Range</td><td class="">设置下载文件的范围，格式为 bytes=first-last</td><td class="">string</td><td class="">否</td></tr><tr><td class="">IfModifiedSince</td><td class="">在指定时间后被修改才返回</td><td class="">string</td><td class="">否</td></tr></tbody></table>


#### 返回结果说明

``` go
{
    'Body': '',
    'Accept-Ranges': 'bytes',
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Range': 'bytes 0-16086/16087',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'X-Cos-Request-Id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Body</td><td class="">下载文件的内容</td><td class="">StreamBody</td></tr><tr><td class="">文件元信息</td><td class="">下载文件的元信息，包括 Etag 和 X-Cos-Request-Id 等信息，也会返回设置的文件元信息</td><td class="">string</td></tr></tbody></table>


### 设置对象复制

复制文件到目标路径（PUT Object-Copy）。




#### 方法原型

``` go
func (s *ObjectService) Copy(ctx context.Context, key, sourceURL string, opt *ObjectCopyOptions) (*ObjectCopyResult, *Response, error)

请求示例

u, _ := url.Parse("http://examplebucket-12500000000.cos.ap-guangzhou.myqcloud.com")
source := "test/objectMove_src"
soruceURL := fmt.Sprintf("%s/%s", u.Host, source)
dest := "test/objectMove_dest"
//opt := &cos.ObjectCopyOptions{}
r, resp, err := client.Object.Copy(context.Background(), dest, soruceURL, nil)

参数说明

type ObjectCopyOptions struct {
    *ObjectCopyHeaderOptions 
    *ACLHeaderOptions        
}
type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}
type ObjectCopyHeaderOptions struct {
    XCosMetadataDirective           string 
    XCosCopySourceIfModifiedSince   string 
    XCosCopySourceIfUnmodifiedSince string 
    XCosCopySourceIfMatch           string 
    XCosCopySourceIfNoneMatch       string 
    XCosStorageClass                string 
    // 自定义的 x-cos-meta-* header
    XCosMetaXXX                        *http.Header 
    XCosCopySource                     string      
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">sourceURL</td><td class="">描述拷贝源文件的 URL</td><td class="">string</td><td class="">是</td></tr><tr><td class="">XCosACL</td><td class="">设置文件的 ACL，如 private，public-read，public-read-write</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予被授权者所有的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予被授权者读的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosMetadataDirective</td><td class="">可选值为 Copy,Replaced，设置为 Copy 时，忽略设置的用户元数据信息直接复制，设置为 Replaced 时，按设置的元信息修改元数据，当目标路径和源路径一样时，必须设置为 Replaced</td><td class="">string</td><td class="">是</td></tr><tr><td class="">XCosCopySourceIfModifiedSince</td><td class="">当 Object 在指定时间后被修改，则执行操作，否则返回412。可与 XCosCopySourceIfNoneMatch 一起使用，与其他条件联合使用返回冲突</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosCopySourceIfUnmodifiedSince</td><td class="">当 Object 在指定时间后未被修改，则执行操作，否则返回412。可与 XCosCopySourceIfMatch 一起使用，与其他条件联合使用返回冲突</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosCopySourceIfMatch</td><td class="">当 Object 的 Etag 和给定一致时，则执行操作，否则返回412。可与 XCosCopySourceIfUnmodifiedSince 一起使用，与其他条件联合使用返回冲突</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosCopySourceIfNoneMatch</td><td class="">当 Object 的 Etag 和给定不一致时，则执行操作，否则返回412。可与 XCosCopySourceIfModifiedSince 一起使用，与其他条件联合使用返回冲突</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosStorageClass</td><td class="">设置文件的存储类型，默认值：STANDARD</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosMetaXXX</td><td class="">用户自定义的文件元信息</td><td class="">http.Header</td><td class="">否</td></tr><tr><td class="">XCosCopySource</td><td class="">源文件 URL 路径，可以通过 versionid 子资源指定历史版本</td><td class="">string</td><td class="">否</td></tr></tbody></table>


#### 返回结果说明

上传文件的属性：



``` go
type ObjectCopyResult struct {
    ETag         string 
    LastModified string
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">ETag</td><td class="">拷贝文件的 MD5 值</td><td class="">string</td></tr><tr><td class="">LastModified</td><td class="">拷贝文件的最后一次修改时间</td><td class="">string</td></tr></tbody></table>


### 删除单个对象


#### 功能说明

在 Bucket 中删除指定 Object （文件/对象）。




#### 方法原型

``` go
func (s *ObjectService) Delete(ctx context.Context, key string) (*Response, error)

请求示例

key := "test/objectPut.go"
resp, err := client.Object.Delete(context.Background(), name)

参数说明

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

删除多个对象

功能说明

在 Bucket 中删除多个 Object （文件/对象）。单次请求最大支持批量删除1000个 Object。

方法原型

func (s *ObjectService) DeleteMulti(ctx context.Context, opt *ObjectDeleteMultiOptions) (*ObjectDeleteMultiResult, *Response, error)

请求示例

var objects []string
objects = append(objects, []string{"a", "b", "c"}...)
obs := []cos.Object{}
for _, v := range names {
    obs = append(obs, cos.Object{Key: v})
}
opt := &cos.ObjectDeleteMultiOptions{
    Objects: obs,
    // 布尔值，这个值决定了是否启动 Quiet 模式。
    // 值为 true 启动 Quiet 模式，值为 false 则启动 Verbose 模式，默认值为 False
    // Quiet: true,
}                                       

v, _, err := c.Object.DeleteMulti(ctx, opt)

参数说明

type ObjectDeleteMultiOptions struct {
    Quiet   bool
    Objects []Object   
}
// Object is the meta info of the object
type Object struct {
    Key          string
    // And other params not relate to this api
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">Quiet</td><td class="">布尔值，这个值决定了是否启动 Quiet 模式。对于响应结果，CSP 提供 Verbose 和 Quiet 两种模式：<br>Verbose 模式将返回每个 Object 的删除结果，Quiet 模式只返回报错的 Object 信息。值为 true 启动 Quiet 模式，值为 false 则启动 Verbose 模式，默认值为 False</td><td class="">Boolean</td><td class="">否</td></tr><tr><td class="">Objects</td><td class="">说明每个将要删除的目标 Object 信息</td><td class="">Container</td><td class="">是</td></tr><tr><td class="">Key</td><td class="">目标 Object 文件名称</td><td class="">String</td><td class="">是</td></tr></tbody></table>




#### 返回结果说明

上传文件的属性：



``` go
// ObjectDeleteMultiResult is the result of DeleteMulti
type ObjectDeleteMultiResult struct {    
    DeletedObjects []Object
    Errors         []struct {
        Key     string
        Code    string
        Message string
    }
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">DeletedObjects</td><td class="">说明每个将要删除的目标 Object 信息</td><td class="">Container</td></tr><tr><td class="">Errors</td><td class="">说明本次删除的失败 Object 信息</td><td class="">Container</td></tr><tr><td class="">Key</td><td class="">删除失败的 Object 的名称</td><td class="">string</td></tr><tr><td class="">Code</td><td class="">删除失败的错误代码</td><td class="">string</td></tr><tr><td class="">Message</td><td class="">删除失败的错误信息</td><td class="">string</td></tr></tbody></table>




## 分块操作


### 查询分片上传


#### 功能说明

查询指定存储桶中正在进行的分块上传信息（List Multipart Uploads）。




#### 方法原型

``` go
func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *Response, error)

请求示例

v, resp, err := c.Bucket.ListMultipartUploads(context.Background(), opt)

参数说明

type ListMultipartUploadsOptions struct {
    Delimiter      string
    EncodingType   string
    Prefix         string
    MaxUploads     int
    KeyMarker      string
    UploadIDMarker string                                         
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">Delimiter</td><td class="">定界符为一个符号，对 Object 名字包含指定前缀且第一次出现 delimiter 字符之间的 Object 作为一组元素：common prefix。如果没有 prefix，则从路径起点开始</td><td class="">string</td><td class="">否</td></tr><tr><td class="">EncodingType</td><td class="">规定返回值的编码格式，合法值：url</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Prefix</td><td class="">限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix</td><td class="">string</td><td class="">否</td></tr><tr><td class="">MaxUploads</td><td class="">设置最大返回的 multipart 数量，合法取值从1到1000，默认1000</td><td class="">string</td><td class="">否</td></tr><tr><td class="">KeyMarker</td><td class="">与 upload-id-marker 一起使用当 upload-id-marker 未被指定时，ObjectName 字母顺序大于 key-marker 的条目将被列出当 upload-id-marker 被指定时，ObjectName 字母顺序大于 key-marker 的条目被列出，ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出</td><td class="">string</td><td class="">否</td></tr><tr><td class="">UploadIDMarker</td><td class="">与 key-marker 一起使用当 key-marker 未被指定时，upload-id-marker 将被忽略当 key-marker 被指定时，ObjectName 字母顺序大于 key-marker 的条目被列出，ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出</td><td class="">string</td><td class="">否</td></tr></tbody></table>




#### 返回结果说明

``` go
// ListMultipartUploadsResult is the result of ListMultipartUploads
type ListMultipartUploadsResult struct {
    Bucket             string
    EncodingType       string
    KeyMarker          string
    UploadIDMarker     string
    NextKeyMarker      string
    NextUploadIDMarker string
    MaxUploads         int
    IsTruncated        bool
    Uploads            []struct {
        Key          string
        UploadID     string
        StorageClass string
        Initiator    *Initiator
        Owner        *Owner
        Initiated    string
    }
    Prefix         string
    Delimiter      string
    CommonPrefixes []string 
}
// Use the same struct with the Owner
type Initiator Owner
// Owner defines Bucket/Object's owner
type Owner struct {
    ID          string
    DisplayName string
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Bucket</td><td class="">分块上传的目标 Bucket，格式为 BucketName，如：examplebucket-1250000000</td><td class="">string</td></tr><tr><td class="">EncodingType</td><td class="">默认不编码，规定返回值的编码方式，可选值：url</td><td class="">string</td></tr><tr><td class="">KeyMarker</td><td class="">列出条目从该 key 值开始</td><td class="">string</td></tr><tr><td class="">UploadIDMarker</td><td class="">列出条目从该 UploadId 值开始</td><td class="">string</td></tr><tr><td class="">NextKeyMarker</td><td class="">假如返回条目被截断，则返回 NextKeyMarker 就是下一个条目的起点</td><td class="">string</td></tr><tr><td class="">NextUploadIDMarker</td><td class="">假如返回条目被截断，则返回 UploadId 就是下一个条目的起点</td><td class="">string</td></tr><tr><td class="">MaxUploads</td><td class="">最多返回的分块的数量，默认为最大的1000</td><td class="">string</td></tr><tr><td class="">IsTruncated</td><td class="">表示返回的分块是否被截断</td><td class="">bool</td></tr><tr><td class="">Uploads</td><td class="">每个 Upload 的信息</td><td class="">Container</td></tr><tr><td class="">Key</td><td class="">Object 的名称</td><td class="">string</td></tr><tr><td class="">UploadID</td><td class="">标示本次分块上传的 ID</td><td class="">string</td></tr><tr><td class="">Key</td><td class="">表示返回的分块是否被截断</td><td class="">bool</td></tr><tr><td class="">StorageClass</td><td class="">用来表示分块的存储级别，默认值：STANDARD</td><td class="">string</td></tr><tr><td class="">Initiator</td><td class="">用来表示本次上传发起者的信息</td><td class="">Container</td></tr><tr><td class="">Owner</td><td class="">用来表示这些分块所有者的信息</td><td class="">Container</td></tr><tr><td class="">Initiated</td><td class="">分块上传的起始时间</td><td class="">string</td></tr><tr><td class="">Prefix</td><td class="">限定返回的 Objectkey 必须以 Prefix 作为前缀，注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix</td><td class="">struct</td></tr><tr><td class="">Delimiter</td><td class="">定界符为一个符号，对 object 名字包含指定前缀且第一次出现 delimiter 字符之间的 object 作为一组元素：common prefix。如果没有prefix，则从路径起点开始</td><td class="">string</td></tr><tr><td class="">CommonPrefixes</td><td class="">将 prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix</td><td class="">string</td></tr><tr><td class="">ID</td><td class="">用户唯一的 CAM 身份 ID</td><td class="">string</td></tr><tr><td class="">DisplayName</td><td class="">用户身份 ID 的简称（UIN）</td><td class="">string</td></tr></tbody></table>




### 分片上传对象

分片上传对象可包括的操作：

- 分片上传对象： 初始化分片上传，上传分片块，完成分块上传。
- 删除已上传分片块。


### <span id = "INIT_MULIT_UPLOAD"> 初始化分片上传 </span>


#### 功能说明

初始化 Multipart Upload 上传操作，获取对应的 uploadId（Initiate Multipart Upload）。




#### 方法原型

``` go
func (s *ObjectService) InitiateMultipartUpload(ctx context.Context, name string, opt *InitiateMultipartUploadOptions) (*InitiateMultipartUploadResult, *Response, error)

请求示例

name := "test_multipart"
//可选opt
v, resp, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil）

参数说明

type InitiateMultipartUploadOptions struct {
    *ACLHeaderOptions       
    *ObjectPutHeaderOptions 
}
type ACLHeaderOptions struct {
    XCosACL              string                           
    XCosGrantRead        string
    XCosGrantWrite       string 
    XCosGrantFullControl string                                           
} 
type ObjectPutHeaderOptions struct {
    CacheControl       string 
    ContentDisposition string 
    ContentEncoding    string 
    ContentType        string 
    ContentLength      int   
    Expires            string 
    // 自定义的 x-cos-meta-* header
    XCosMetaXXX        *http.Header 
    XCosStorageClass   string      
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">r</td><td class="">上传文件的内容，可以为文件流或字节流，当 r 不是`bytes.Buffer/bytes.Reader/strings.Reader`时，必须指定`opt.ObjectPutHeaderOptions.ContentLength`</td><td class="">io.Reader</td><td class="">是</td></tr><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">XCosACL</td><td class="">设置文件的ACL，如 private，public-read</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予被授权者所有的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予被授权者读的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosStorageClass</td><td class="">设置文件的存储类型，默认值：STANDARD</td><td class="">string</td><td class="">否</td></tr><tr><td class="">Expires</td><td class="">设置 Content-Expires</td><td class="">string</td><td class="">否</td></tr><tr><td class="">CacheControl</td><td class="">缓存策略，设置 Cache-Control</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentType</td><td class="">内容类型，设置 Content-Type</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentDisposition</td><td class="">文件名称，设置 Content-Disposition</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentEncoding</td><td class="">编码格式，设置 Content-Encoding</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ContentLength</td><td class="">设置传输长度</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosMetaXXX</td><td class="">用户自定义的文件元信息， 必须以 x-cos-meta 开头，否则会被忽略</td><td class="">http.Header</td><td class="">否</td></tr></tbody></table>




#### 返回结果说明

``` go
type InitiateMultipartUploadResult struct {
    Bucket   string
    Key      string
    UploadID string
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">UploadId</td><td class="">标识分块上传的 ID</td><td class="">string</td></tr><tr><td class="">Bucket</td><td class="">Bucket 名称，由 bucket-appid 组成</td><td class="">string</td></tr><tr><td class="">Key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg ` 中，对象键为 doc/pic.jpg</td><td class="">string</td></tr></tbody></table>




### <span id = "MULIT_UPLOAD_PART"> 上传分块 </span>

分块上传对象（Upload Part）。




#### 方法原型

``` go
func (s *ObjectService) UploadPart(ctx context.Context, key, uploadID string, partNumber int, r io.Reader, opt *ObjectUploadPartOptions) (*Response, error)

请求示例

// 注意，上传分块的块数最多10000块
key := "test/test_multi_upload.go"
f := strings.NewReader("test heoo")
// opt可选
_, err := client.Object.UploadPart(
    context.Background(), key, uploadID, 1, f, nil,
)

参数说明

type ObjectUploadPartOptions struct {
    ContentLength   int
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">UploadId</td><td class="">标识分块上传的 ID，由 InitiateMultipartUpload 生成</td><td class="">string</td><td class="">是</td></tr><tr><td class="">PartNumber</td><td class="">标识上传分块的序号</td><td class="">int</td><td class="">是</td></tr><tr><td class="">r</td><td class="">上传分块的内容，可以为本地文件流或输入流。当 r 不是`bytes.Buffer/bytes.Reader/strings.Reader`时，必须指定 opt.ContentLength</td><td class="">io.Reader</td><td class="">是</td></tr><tr><td class="">ContentLength</td><td class="">设置传输长度</td><td class="">int</td><td class="">否</td></tr></tbody></table>




#### 返回结果说明

``` go
{
    'ETag': 'string'
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">ETag</td><td class="">上传分块的 MD5 值</td><td class="">string</td></tr></tbody></table>




### <span id = "LIST_MULIT_UPLOAD"> 查询已上传块 </span>


#### 功能说明

查询特定分块上传操作中的已上传的块（List Parts）。




#### 方法原型

``` go
func (s *ObjectService) ListParts(ctx context.Context, name, uploadID string, opt *ObjectListPartsOptions) (*ObjectListPartsResult, *Response, error)

请求示例

key := "test/test_list_parts.go"
v, resp, err := client.Object.ListParts(context.Background(), key, uploadID, nil)

参数说明

type ObjectListPartsOptions struct {
    EncodingType     string
    MaxParts         string
    PartNumberMarker string                                      
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg ` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">UploadId</td><td class="">标识分块上传的 ID，由 InitiateMultipartUpload 生成</td><td class="">string</td><td class="">是</td></tr><tr><td class="">EncodingType</td><td class="">规定返回值的编码方式</td><td class="">string</td><td class="">否</td></tr><tr><td class="">MaxParts</td><td class="">单次返回最大的条目数量，默认1000</td><td class="">string</td><td class="">否</td></tr><tr><td class="">PartNumberMarker</td><td class="">默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始</td><td class="">string</td><td class="">否</td></tr></tbody></table>




#### 返回结果说明

``` go
type ObjectListPartsResult struct {
    Bucket               string
    EncodingType         string
    Key                  string
    UploadID             string
    Initiator            *Initiator
    Owner                *Owner
    StorageClass         string
    PartNumberMarker     string
    NextPartNumberMarker string
    MaxParts             string
    IsTruncated          bool
    Parts                []Object
}
type Initiator struct {
    UIN         string
    ID          string
    DisplayName string
}
type Owner struct {
    UIN         string
    ID          string
    DisplayName string
}
type Object struct {
    Key          string
    ETag         string
    Size         int
    PartNumber   int
    LastModified string
    StorageClass string 
    Owner        *Owner
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Bucket</td><td class="">存储桶名称，格式：BucketName-APPID。例如 examplebucket-1250000000</td><td class="">string</td></tr><tr><td class="">EncodingType</td><td class="">默认不编码，规定返回值的编码方式，可选值：url</td><td class="">string</td></tr><tr><td class="">Key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td></tr><tr><td class="">UploadId</td><td class="">标识分块上传的 ID，由 InitiateMultipartUpload 生成</td><td class="">string</td></tr><tr><td class="">Initiator</td><td class="">分块上传的创建者，包括 DisplayName，UIN 和 ID</td><td class="">struct</td></tr><tr><td class="">Owner</td><td class="">文件拥有者的信息，包括 DisplayName ，UIN 和 ID</td><td class="">struct</td></tr><tr><td class="">StorageClass</td><td class="">文件的存储类型，默认值：STANDARD</td><td class="">string</td></tr><tr><td class="">PartNumberMarker</td><td class="">默认为0，从第一块列出分块，从 PartNumberMarker 下一个分块开始列出</td><td class="">string</td></tr><tr><td class="">NextPartNumberMarker</td><td class="">指明下一次列出分块的起始位置</td><td class="">string</td></tr><tr><td class="">MaxParts</td><td class="">最多返回的分块的数量，默认为最大的1000</td><td class="">string</td></tr><tr><td class="">IsTruncated</td><td class="">表示返回的分块是否被截断</td><td class="">bool</td></tr><tr><td class="">Part</td><td class="">上传分块的相关信息，包括 ETag，PartNumber，Size，LastModified</td><td class="">struct</td></tr></tbody></table>




### <span id = "COMPLETE_MULIT_UPLOAD"> 完成分块上传 </span>


#### 功能说明

完成整个文件的分块上传（Complete Multipart Upload）。




#### 方法原型

``` go
func (s *ObjectService) CompleteMultipartUpload(ctx context.Context, key, uploadID string, opt *CompleteMultipartUploadOptions) (*CompleteMultipartUploadResult, *Response, error)

请求示例

// 封装 UploadPart 接口返回 etag 信息
func uploadPart(c *cos.Client, name string, uploadID string, blockSize, n int) string {
    b := make([]byte, blockSize)
    if _, err := rand.Read(b); err != nil {
        panic(err)
    }
    s := fmt.Sprintf("%X", b)
    f := strings.NewReader(s)

    // 当传入参数 f 不是 bytes.Buffer/bytes.Reader/strings.Reader 时，必须指定 opt.ContentLength
    // opt := &cos.ObjectUploadPartOptions{
    //     ContentLength: size,
    // }

    resp, err := c.Object.UploadPart(
        context.Background(), name, uploadID, n, f, nil,
    )
    if err != nil {
        panic(err)
    }
    return resp.Header.Get("Etag")
}

// Init, UploadPart and Complete process
key := "test/test_complete_upload.go"
v, resp, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)
uploadID := v.UploadID
blockSize := 1024 * 1024 * 3

opt := &cos.CompleteMultipartUploadOptions{}
for i := 1; i < 5; i++ {
    // 调用上面封装的接口获取 etag 信息
    etag := uploadPart(c, key, uploadID, blockSize, i)
    opt.Parts = append(opt.Parts, cos.Object{
        PartNumber: i, ETag: etag},
    )
}

v, resp, err = client.Object.CompleteMultipartUpload(
    context.Background(), key, uploadID, opt,
)

参数说明

type CompleteMultipartUploadOptions struct {
    Parts   []Object 
}
type Object struct { 
    ETag         string 
    PartNumber   int     
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">UploadId</td><td class="">标识分块上传的 ID，由 InitiateMultipartUpload 生成</td><td class="">string</td><td class="">是</td></tr><tr><td class="">CompleteMultipartUploadOptions</td><td class="">所有分块的 ETag 和 PartNumber 信息</td><td class="">struct</td><td class="">是</td></tr></tbody></table>




#### 返回结果说明

``` go
type CompleteMultipartUploadResult struct {
    Location string
    Bucket   string
    Key      string
    ETag     string
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Location</td><td class="">URL 地址</td><td class="">string</td></tr><tr><td class="">Bucket</td><td class="">存储桶名称，格式：BucketName-APPID。例如 examplebucket-1250000000</td><td class="">string</td></tr><tr><td class="">Key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg ` 中，对象键为 doc/pic.jpg</td><td class="">string</td></tr><tr><td class="">ETag</td><td class="">合并后对象的唯一标签值，该值不是对象内容的 MD5 校验值，仅能用于检查对象唯一性。如需校验文件内容，可以在上传过程中校验单个分块的 ETag 值</td><td class="">string</td></tr></tbody></table>




### <span id = "ABORT_MULIT_UPLOAD"> 终止分块上传 </span>


#### 功能说明

终止一个分块上传操作并删除已上传的块（Abort Multipart Upload）。




#### 方法原型

``` go
func (s *ObjectService) AbortMultipartUpload(ctx context.Context, key, uploadID string) (*Response, error)

请求示例

key := "test_multipart.txt"
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)
// Abort
resp, err := client.Object.AbortMultipartUpload(context.Background(), key, v.UploadID)

参数说明

参数名称	参数描述	类型	必填
key	对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg ` 中，对象键为 doc/pic.jpg	string	是
UploadId	标识分块上传的 ID	string	是

其他操作

设置对象 ACL

功能说明

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

方法原型

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

请求示例

// 1.Set by header
opt := &cos.ObjectPutACLOptions{
    Header: &cos.ACLHeaderOptions{
        XCosACL: "private",
    },
}
key := "test/hello.txt"
resp, err := client.Object.PutACL(context.Background(), key, opt)
// 2.Set by body
opt = &cos.ObjectPutACLOptions{
    Body: &cos.ACLXml{
        Owner: &cos.Owner{
            ID: "qcs::cam::uin/100000760461:uin/100000760461",
        },
        AccessControlList: []cos.ACLGrant{
            {
                Grantee: &cos.ACLGrantee{
                    Type: "RootAccount",
                    ID:   "qcs::cam::uin/100000760461:uin/100000760461",
                },

                Permission: "FULL_CONTROL",
            },
        },
    },
}

resp, err = client.Object.PutACL(context.Background(), key, opt)

参数说明

type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">key</td><td class="">对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg ` 中，对象键为 doc/pic.jpg</td><td class="">string</td><td class="">是</td></tr><tr><td class="">XCosACL</td><td class="">设置 Object 的 ACL，如 private，public-read</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantFullControl</td><td class="">赋予被授权者所有的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">XCosGrantRead</td><td class="">赋予被授权者读的权限。格式：id="[OwnerUin]"</td><td class="">string</td><td class="">否</td></tr><tr><td class="">ACLXML</td><td class="">赋予指定账户对 Bucket 的访问权限，具体格式见 get object acl 返回结果说明</td><td class="">struct</td><td class="">否</td></tr></tbody></table>




### 查询对象 ACL


#### 功能说明

查询 Object（文件/对象）的 ACL（GET Object acl）。




#### 方法原型

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

请求示例

key := "test/hello.txt"
v, resp, err := client.Object.GetACL(context.Background(), key)

参数说明

参数名称	参数描述	类型	必填
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 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td></tr></thead><tbody><tr><td class="">Owner</td><td class="">Bucket 拥有者的信息，包括 DisplayName 和 ID</td><td class="">struct</td></tr><tr><td class="">AccessControlList</td><td class="">Bucket 权限授予者的信息，包括 Grantee 和 Permission</td><td class="">struct</td></tr><tr><td class="">Grantee</td><td class="">权限授予者的信息，包括 DisplayName，Type，ID 和 UIN</td><td class="">struct</td></tr><tr><td class="">Type</td><td class="">权限授予者的类型，类型为 CanonicalUser 或者 Group</td><td class="">string</td></tr><tr><td class="">ID</td><td class="">Type 为 CanonicalUser 时，对应权限授予者的 ID</td><td class="">string</td></tr><tr><td class="">DisplayName</td><td class="">权限授予者的名字</td><td class="">string</td></tr><tr><td class="">UIN</td><td class="">Type 为 Group 时，对应权限授予者的 UIN</td><td class="">string</td></tr><tr><td class="">Permission</td><td class="">授予者所拥有的 Bucket 的权限，可选值有 FULL_CONTROL，WRITE，READ，分别对应读写权限、写权限、读权限</td><td class="">string</td></tr></tbody></table>




# 存储桶管理


## 简介

本文档提供关于跨域访问、生命周期、版本控制和跨地域复制相关的 API 概览以及 SDK 示例代码。



**跨域访问**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">PUT Bucket cors</td><td class="">设置跨域配置</td><td class="">设置存储桶的跨域访问权限</td></tr><tr><td class="">GET Bucket cors</td><td class="">查询跨域配置</td><td class="">查询存储桶的跨域访问配置信息</td></tr><tr><td class="">DELETE Bucket cors</td><td class="">删除跨域配置</td><td class="">删除存储桶的跨域访问配置信息</td></tr></tbody></table>

**版本控制**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">PUT Bucket versioning</td><td class="">设置版本控制</td><td class="">设置存储桶的版本控制功能</td></tr><tr><td class="">GET Bucket versioning</td><td class="">查询版本控制</td><td class="">查询存储桶的版本控制信息</td></tr></tbody></table>

**跨地域复制**


<table class="doc-table-container indent-undefined"><thead><tr><td class="">API</td><td class="">操作名</td><td class="">操作描述</td></tr></thead><tbody><tr><td class="">PUT Bucket replication</td><td class="">设置跨地域复制</td><td class="">设置存储桶的跨地域复制规则</td></tr><tr><td class="">GET Bucket replication</td><td class="">查询跨地域复制</td><td class="">查询存储桶的跨地域复制规则</td></tr><tr><td class="">DELETE Bucket replication</td><td class="">删除跨地域复制</td><td class="">删除存储桶的跨地域复制规则</td></tr></tbody></table>




## 跨域访问


### 设置跨域配置


#### 功能说明

设置指定存储桶的跨域访问配置信息（PUT Bucket cors）。




#### 方法原型

``` go
func (s *BucketService) PutCORS(ctx context.Context, opt *BucketPutCORSOptions) (*Response, error)

请求示例

opt := &cos.BucketPutCORSOptions{
    Rules: []cos.BucketCORSRule{
        {
            AllowedOrigins: []string{"http://www.qq.com"},
            AllowedMethods: []string{"PUT", "GET"},
            AllowedHeaders: []string{"x-cos-meta-test", "x-cos-xx"},
            MaxAgeSeconds:  500,
            ExposeHeaders:  []string{"x-cos-meta-test1"},
        },
        {
            ID:             "1234",
            AllowedOrigins: []string{"http://www.baidu.com", "twitter.com"},
            AllowedMethods: []string{"PUT", "GET"},
            MaxAgeSeconds:  500,
        },
    },
}
resp, err := client.Bucket.PutCORS(context.Background(), opt)

参数说明

type BucketCORSRule struct {
    ID             string   
    AllowedMethods []string 
    AllowedOrigins []string 
    AllowedHeaders []string 
    MaxAgeSeconds  int      
    ExposeHeaders  []string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">BucketCORSRule</td><td class="">设置对应的跨域规则，包括 ID，MaxAgeSeconds，AllowedOrigin，AllowedMethod，AllowedHeader，ExposeHeader</td><td class="">struct</td><td class="">是</td></tr><tr><td class="">ID</td><td class="">设置规则的 ID</td><td class="">string</td><td class="">否</td></tr><tr><td class="">AllowedMethods</td><td class="">设置允许的方法，如 GET，PUT，HEAD，POST，DELETE</td><td class="">[]string</td><td class="">是</td></tr><tr><td class="">AllowedOrigins</td><td class="">设置允许的访问来源，如 `"http://gsesgpucloud.com"`，支持通配符 *</td><td class="">[]string</td><td class="">是</td></tr><tr><td class="">AllowedHeaders</td><td class="">设置请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *</td><td class="">[]string</td><td class="">否</td></tr><tr><td class="">MaxAgeSeconds</td><td class="">设置 OPTIONS 请求得到结果的有效期</td><td class="">int</td><td class="">否</td></tr><tr><td class="">ExposeHeaders</td><td class="">设置浏览器可以接收到的来自服务器端的自定义头部信息</td><td class="">[]string</td><td class="">否</td></tr></tbody></table>




### 查询跨域配置


#### 功能说明

查询存储桶的跨域访问配置信息（GET Bucket cors）。




#### 方法原型

``` go
func (s *BucketService) GetCORS(ctx context.Context) (*BucketGetCORSResult, *Response, error)

请求示例

v, resp, err := client.Bucket.GetCORS(context.Background())

返回结果说明

通过 GetBucketCORSResult 返回请求结果。

type BucketCORSRule struct {
    ID             string   
    AllowedMethods []string 
    AllowedOrigins []string 
    AllowedHeaders []string 
    MaxAgeSeconds  int      
    ExposeHeaders  []string 
}
```<table class="doc-table-container indent-undefined"><thead><tr><td class="">参数名称</td><td class="">参数描述</td><td class="">类型</td><td class="">必填</td></tr></thead><tbody><tr><td class="">BucketCORSRule</td><td class="">设置对应的跨域规则，包括 ID，MaxAgeSeconds，AllowedOrigin，AllowedMethod，AllowedHeader，ExposeHeader</td><td class="">struct</td><td class="">是</td></tr><tr><td class="">ID</td><td class="">设置规则的 ID</td><td class="">string</td><td class="">否</td></tr><tr><td class="">AllowedMethods</td><td class="">设置允许的方法，如 GET，PUT，HEAD，POST，DELETE</td><td class="">[]string</td><td class="">是</td></tr><tr><td class="">AllowedOrigins</td><td class="">设置允许的访问来源，如 `"http://gsesgpucloud.com"`，支持通配符 *</td><td class="">[]string</td><td class="">是</td></tr><tr><td class="">AllowedHeaders</td><td class="">设置请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *</td><td class="">[]string</td><td class="">否</td></tr><tr><td class="">MaxAgeSeconds</td><td class="">设置 OPTIONS 请求得到结果的有效期</td><td class="">int</td><td class="">否</td></tr><tr><td class="">ExposeHeaders</td><td class="">设置浏览器可以接收到的来自服务器端的自定义头部信息</td><td class="">[]string</td><td class="">否</td></tr></tbody></table>




### 删除跨域配置


#### 功能说明

删除指定存储桶的跨域访问配置（DELETE Bucket cors）。




#### 方法原型

``` go
func (s *BucketService) DeleteCORS(ctx context.Context) (*Response, error)

请求示例

resp, err := client.Bucket.DeleteCORS(context.Background())

预签名

简介

Go SDK 提供获取请求预签名 URL 接口，详细操作请查看本文示例。

获取请求预签名 URL

func (s *ObjectService) GetPresignedURL(ctx context.Context, httpMethod, name, ak, sk string, expired time.Duration, opt interface{}) (*url.URL, error)

参数说明

参数名称	类型	描述
httpMethod	string	HTTP 请求方法
name	string	HTTP 请求路径，即对象键
ak	string	SecretId
sk	string	SecretKey
expired	time.Duration	签名有效时长
opt	interface{}	扩展项，可填 nil

永久密钥预签名请求示例

上传请求示例

name := "test/objectPut.go"
ctx := context.Background()
// NewReader create file content
f := strings.NewReader("test")

// 1.Normal add auth header way to put object
_, err := c.Object.Put(ctx, name, f, nil)
if err != nil {
    panic(err)
}
// Get presigned
presignedURL, err := c.Object.PresignedURL(ctx, http.MethodPut, name, ak, sk, time.Hour, nil)
if err != nil {
    panic(err)
}
// 2.Put object content by presinged url
data := "test upload with presignedURL"
f = strings.NewReader(data)
req, err := http.NewRequest(http.MethodPut, presignedURL.String(), f)
if err != nil {
    panic(err)
}
// Can set request header.
req.Header.Set("Content-Type", "text/html")
_, err = http.DefaultClient.Do(req)
if err != nil {
    panic(err)
}

下载请求示例

name := "test"
ctx := context.Background()
// 1.Normal add auth header way to get object
resp, err := c.Object.Get(ctx, name, nil)
if err != nil {
    panic(err)
} 
bs, _ := ioutil.ReadAll(resp.Body)
resp.Body.Close()
// Get presigned
presignedURL, err := c.Object.GetPresignedURL(ctx, http.MethodGet, name, ak, sk, time.Hour, nil)
if err != nil {
    panic(err)
} 
// 2.Get object content by presinged url
resp2, err := http.Get(presignedURL.String())
if err != nil {
    panic(err)
}                    
bs2, _ := ioutil.ReadAll(resp2.Body)
resp2.Body.Close()
fmt.Printf("result2 is : %s\n", string(bs2))
fmt.Printf("%v\n\n", bytes.Compare(bs2, bs) == 0)

异常处理

简介

API 返回的 Response 为 Golang HTTP 标准库 Response 类型。用户可通过 err.Error() 获取错误提示，服务端返回的具体信息，请参见 [CSP 错误码]。

服务端异常

API 返回的 Response 结构中包含调用结构，如下所示：

成员	描述	类型
X-Cos-Request-Id	Response 中响应头，请求 ID，用于表示一个请求，对于排查问题十分重要	string
StatusCode	Response 的 status 状态码，4xx 是指请求因客户端而失败，5xx 是服务端异常导致的失败，详情请参见[ CSP 错误码]	string