对象存储
文档捉虫大赛：人工智能与机器学习专题> HOT
文档中心 > 对象存储 > SDK 文档 > Go SDK > 对象操作 > 上传对象

上传对象

最近更新时间：2023-08-24 17:42:12

我的收藏

本页目录：

简介

本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
简单操作
API
操作名
操作描述
简单上传对象
上传一个对象至存储桶
追加上传对象
使用分块追加的方式上传对象
分块操作
API
操作名
操作描述
查询分块上传
查询正在进行中的分块上传信息
初始化分块上传
初始化 Multipart Upload 上传操作
上传分块
分块上传文件
查询已上传块
查询特定分块上传操作中的已上传的块
完成分块上传
完成整个文件的分块上传
终止分块上传
终止一个分块上传操作并删除已上传的块

高级接口（推荐）

上传对象

功能说明

上传接口根据用户文件的长度，自动切分数据， 降低用户的使用门槛，用户无需关心分块上传的每个步骤，当文件大小大于16MB，采用分块上传，用户可通过 PartSize 参数调整。

方法原型

func (s *ObjectService) Upload(ctx context.Context, key string, filepath string, opt *MultiUploadOptions) (*CompleteMultipartUploadResult, *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.Upload(
        context.Background(), key, "localfile", nil,
    )
    if err != nil {
        panic(err)
    }
}

参数说明

type MultiUploadOptions struct {
    OptIni             *InitiateMultipartUploadOptions
    PartSize           int64
    ThreadPoolSize     int
    CheckPoint         bool
}
参数名称
参数描述
类型
是否必填
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中，对象键为 doc/pic.jpg
string
是
filepath
本地文件名
string
是
opt
对象属性
Struct
否
OptIni
设置对象属性和 ACL，详情请参见 InitiateMultipartUploadOptions
Struct
否
PartSize
块大小，单位为 MB，如果用户不指定或者指定 partSize <= 0，由 Go SDK 自动切分，新版本默认大小为16MB
int
否
ThreadPoolSize
线程池大小，默认为1
int
否
CheckPoint
是否开启断点续传，默认为 false
bool
否

返回结果说明

type CompleteMultipartUploadResult struct {
    Location string
    Bucket   string
    Key      string
    ETag     string
}

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

简单操作

简单上传对象

功能说明

上传一个 Object（文件/对象）至存储桶（PUT Object）。最大支持5GB（含），5GB以上的对象请使用 分块上传 或 高级接口 上传。支持简单上传对象、创建文件夹、批量上传操作。

方法原型

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

请求示例1：上传对象

package main

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

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

    // Case1 使用 Put 上传对象
    key := "exampleobject"
    f, err := os.Open("../test")
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentType: "text/html",
        },
        ACLHeaderOptions: &cos.ACLHeaderOptions{
            // 如果不是必要操作，建议上传文件时不要给单个文件设置权限，避免达到限制。若不设置默认继承桶的权限。
            XCosACL: "private",
        },
    }
    _, err = client.Object.Put(context.Background(), key, f, opt)
    if err != nil {
        panic(err)
    }

    // Case 2 使用 PUtFromFile 上传本地文件到 COS
    filepath := "./test"
    _, err = client.Object.PutFromFile(context.Background(), key, filepath, opt)
    if err != nil {
        panic(err)
    }

    // Case 3 上传 0 字节文件, 设置输入流长度为 0 
    _, err = client.Object.Put(context.Background(), key, strings.NewReader(""), nil)
    if err != nil {
        // ERROR
    }
}

请求示例2：创建文件夹

COS 上可以将以 '/' 分隔的对象路径看做虚拟文件夹，根据此特性，可以上传一个空的流，并且命名以 '/' 结尾，可实现在 COS 上创建一个空文件夹。
package main

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

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

    // 文件夹名称
    name := "folder/"
    // 传递大小为0的输入流
    _, err := client.Object.Put(context.Background(), name, strings.NewReader(""), nil)
    if err != nil {
        // ERROR
    }
}

请求示例3：上传到虚拟目录

上传由 '/' 分隔的对象名，自动创建包含文件的文件夹。想要在此文件夹中添加新文件时，只需要在上传文件至 COS 时，将 Key 填写为此目录前缀即可。
package main

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

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

    dir := "exampledir/"
    filename := "exampleobject"
    key := dir + filename
    f := strings.NewReader("test file")
    _, err = client.Object.Put(context.Background(), key, f, nil)
    if err != nil {
        // ERROR
    }
}

请求示例4：查看上传进度

package main

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

type SelfListener struct {
}

// 自定义进度回调，需要实现 ProgressChangedCallback 方法
func (l *SelfListener) ProgressChangedCallback(event *cos.ProgressEvent) {
    switch event.EventType {
    case cos.ProgressDataEvent:
        fmt.Printf("\\r[ConsumedBytes/TotalBytes: %d/%d, %d%%]",
            event.ConsumedBytes, event.TotalBytes, event.ConsumedBytes*100/event.TotalBytes)
    case cos.ProgressFailedEvent:
        fmt.Printf("\\nTransfer Failed: %v", event.Err)
    }
}
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
        },
    })
    // Case 1 通过默认回调查看上传进度
    key := "exampleobject"
    f, err := os.Open("test")
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentType: "text/html",
            // 设置默认的进度回调函数
            Listener: &cos.DefaultProgressListener{},
        },
        ACLHeaderOptions: &cos.ACLHeaderOptions{
            // 如果不是必要操作，建议上传文件时不要给单个文件设置权限，避免达到限制。若不设置默认继承桶的权限。
            XCosACL: "private",
        },
    }
    _, err = client.Object.Put(context.Background(), key, f, opt)
    if err != nil {
        panic(err)
    }
    // Case 2 通过自定义方式查看上传进度
    opt.Listener = &SelfListener{}
    filepath := "./test"
    _, err = client.Object.PutFromFile(context.Background(), key, filepath, opt)
    if err != nil {
        panic(err)
    }
}

请求示例5：多线程批量上传

package main

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

func upload(wg *sync.WaitGroup, c *cos.Client, files <-chan string) {
    defer wg.Done()
    for file := range files {
        name := "folder/" + file
        fd, err := os.Open(file)
        if err != nil {
            //ERROR
            continue
        }
        _, err = c.Object.Put(context.Background(), name, fd, nil)
        if err != nil {
            //ERROR
        }
    }
}
func main() {
    u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
        },
    })
    // 多线程批量上传文件
    filesCh := make(chan string, 2)
    filePaths := []string{"test1", "test2", "test3"}
    var wg sync.WaitGroup
    threadpool := 2
    for i := 0; i < threadpool; i++ {
        wg.Add(1)
        go upload(&wg, c, filesCh)
    }
    for _, filePath := range filePaths {
        filesCh <- filePath
    }
    close(filesCh)
    wg.Wait()
}

请求示例6：MD5校验

Go SDK v0.7.23及以上版本, 上传文件时默认都已开启了CRC64校验，用户也可自行做MD5校验。
package main
import (
    "context"
    "crypto/md5"
    "encoding/base64"
    "fmt"
    "github.com/tencentyun/cos-go-sdk-v5"
    "io/ioutil"
    "net/http"
    "net/url"
    "os"
    "strings"
)

func calMD5Digest(msg []byte) []byte {
    m := md5.New()
    m.Write(msg)
    return m.Sum(nil)
}

func main() {
    u, _ := url.Parse("https://test-1259654469.cos.ap-guangzhou.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := 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
        },
    })
    // Go SDK v0.7.23及以上版本, 上传文件时默认都开启了 CRC64校验
    // c.Conf.EnableCRC = false // 手动关闭 CRC64校验，强烈不建议用户关闭 CRC64校验

    // 计算 MD5
    content := "test content"
    bs1 := calMD5Digest([]byte(content))
    md5str := fmt.Sprintf("%x", bs1)

    name := "exampleobject"
    f := strings.NewReader(content)
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentMD5:  base64.StdEncoding.EncodeToString(bs1), // 上传时服务器根据收到的文件和该值做校验
            XCosMetaXXX: &http.Header{},
        },
        ACLHeaderOptions: nil,
    }
    opt.XCosMetaXXX.Add("x-cos-meta-md5", md5str) // 下载时业务可通过该值做文件校验

    // 上传文件
    _, err := c.Object.Put(context.Background(), name, f, opt)
    if err != nil {
        // ERROR
    }

    // 下载文件
    resp, err := c.Object.Get(context.Background(), name, nil)
    if err != nil {
        // ERROR
    }
    defer resp.Body.Close()

    meta_md5 := resp.Header.Get("x-cos-meta-md5")
    body, _ := ioutil.ReadAll(resp.Body)
    bs2 := calMD5Digest(body)
    if fmt.Sprintf("%x", bs2) != meta_md5 {
        fmt.Printf("md5 is not consistent\\n")
    }
}

参数说明

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 
    ContentMD5         string 
    ContentLength      int64  
    Expires            string 
    // 自定义的 x-cos-meta-* header
    XCosMetaXXX        *http.Header 
    XCosStorageClass   string      
    XCosTrafficLimit   int
    Listener           ProgressListener
}
参数名称
参数描述
类型
是否必填
r
上传文件的内容，可以为文件流或字节流，当 r 不是 bytes.Buffer/bytes.Reader/strings.Reader 时，必须指定 opt.ObjectPutHeaderOptions.ContentLength
io.Reader
是
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为 doc/pic.jpg
string
是
XCosACL
设置文件的 ACL，例如 private，public-read，public-read-write
string
否
XCosGrantFullControl
赋予被授权者所有的权限。格式：id="[OwnerUin]"
string
否
XCosGrantRead
赋予被授权者读的权限。格式：id="[OwnerUin]"
string
否
XCosStorageClass
文件的存储类型，例如 STANDARD、STANDARD_IA、ARCHIVE，默认值：STANDARD。更多存储类型，请参见 存储类型概述
string
否
Expires
设置 Content-Expires
string
否
CacheControl
缓存策略，设置 Cache-Control
string
否
ContentType
内容类型，设置 Content-Type
string
否
ContentMD5
RFC 1864中定义的请求体内容的16字节二进制 MD5 哈希值的 Base64 编码形式，用于完整性检查，验证请求体在传输过程中是否发生变化，最终的取值长度应为24个字符，请注意在编写代码时使用正确的方法和参数，例如 ZzD3iDJdrMAAb00lgLLeig==
string
否
ContentDisposition
文件名称，设置 Content-Disposition
string
否
ContentEncoding
编码格式，设置 Content-Encoding
string
否
ContentLength
设置传输长度
int64
否
XCosMetaXXX
用户自定义的文件元信息， 必须以 x-cos-meta 开头，否则会被忽略
http.Header
否
XCosTrafficLimit
设置单链接限速
int
否
Listener
进度回调接口
Struct
否

返回结果说明

{
    'ETag': 'string',
    'x-cos-expiration': 'string'
}
通过返回结果 Response 获取。
resp, err := client.Object.Put(context.Background(), key, f, nil)
etag := resp.Header.Get("ETag")
exp := resp.Header.Get("x-cos-expiration")
参数名称
参数描述
类型
ETag
上传文件的 MD5 值
string
x-cos-expiration
设置生命周期后，返回文件过期规则
string

追加上传对象

功能说明

以分块追加的方式上传对象（APPEND Object）。

方法原型

func (s *ObjectService) Append(ctx context.Context, name string, position int, r io.Reader, opt *ObjectPutOptions) (int, *Response, error)

请求示例

package main

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

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

    name := "exampleobject"
    pos, _, err := client.Object.Append(context.Background(), name, 0, strings.NewReader("test1"), nil)
    if err != nil {
        // ERROR
    }
    _, _, err = client.Object.Append(context.Background(), name, pos, strings.NewReader("test2"), nil)
    if err != nil {
        // ERROR
    }
}

参数说明

参数名称
参数描述
类型
name
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为 doc/pic.jpg
string
position
追加操作的起始点，单位为字节。首次追加则设置 Position=0，后续追加则设置 Position 为当前 Object 的 content-length
int
r
上传文件的内容，可以为文件流或字节流，当 r 不是 bytes.Buffer/bytes.Reader/strings.Reader时，必须指定 opt.ObjectPutHeaderOptions.ContentLength
io.Reader
opt
上传参数，详见 ObjectPutOptions
struct

返回结果说明

参数名称
参数描述
类型
x-cos-next-append-position
下一次追加操作的起始点，单位：字节
int

分块操作

关于分块上传的更多说明请参见 分块上传。分块上传对象可包括的操作如下：
分块上传对象：初始化分块上传，上传分块，完成所有分块上传。
分块续传：查询已上传的分块，上传分块，完成所有分块上传。
删除已上传分块。

查询分块上传

功能说明

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

方法原型

func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *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.ListMultipartUploads(context.Background(), nil)
    if err != nil {
        panic(err)
    }
}

参数说明

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

返回结果说明

// ListMultipartUploadsResult 保存 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 
}
// 与 Owner 使用同样的结构
type Initiator Owner
// Owner 定义了 Bucket/Object's 拥有者
type Owner struct {
    ID          string
    DisplayName string
}
参数名称
参数描述
类型
Bucket
分块上传的目标 Bucket，格式为 BucketName，例如 examplebucket-1250000000
string
EncodingType
默认不编码，规定返回值的编码方式，可选值：url
string
KeyMarker
列出条目从该 key 值开始
string
UploadIDMarker
列出条目从该 UploadId 值开始
string
NextKeyMarker
假如返回条目被截断，则返回 NextKeyMarker 就是下一个条目的起点
string
NextUploadIDMarker
假如返回条目被截断，则返回 UploadId 就是下一个条目的起点
string
MaxUploads
最多返回的分块的数量，默认为最大的1000
string
IsTruncated
表示返回的分块是否被截断
bool
Uploads
每个 Upload 的信息
Container
Key
Object 的名称
string
UploadID
表示本次分块上传的 ID
string
Key
表示返回的分块是否被截断
bool
StorageClass
用来表示分块的存储类型，例如 STANDARD、STANDARD_IA、ARCHIVE，默认值：STANDARD。更多存储类型，请参见 存储类型概述
string
Initiator
用来表示本次上传发起者的信息
Container
Owner
用来表示这些分块所有者的信息
Container
Initiated
分块上传的起始时间
string
Prefix
限定返回的 Objectkey 必须以 Prefix 作为前缀，注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix
struct
Delimiter
定界符为一个符号，对 object 名字包含指定前缀且第一次出现 delimiter 字符之间的 object 作为一组元素：common prefix。如果没有prefix，则从路径起点开始
string
CommonPrefixes
将 prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix
string
ID
用户唯一的 CAM 身份 ID
string
DisplayName
用户身份 ID 的简称（UIN）
string

分块上传对象

分块上传对象可包括的操作：
分块上传对象： 初始化分块上传，上传分块，完成分块上传。
删除已上传分块。
说明
分块上传对象，您还可以使用 高级接口 上传（推荐）。

初始化分块上传

功能说明

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

方法原型

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

请求示例

package main

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

func main()