tencent cloud

文档反馈

上传对象

最后更新时间:2022-05-23 11:50:02

    简介

    本文档提供关于对象的上传操作的 API 概览以及 SDK 示例代码。

    简单操作

    API 操作名 操作描述
    PUT Object 简单上传对象 上传一个 Object(文件/对象)至 Bucket
    APPEND Object 追加上传对象 使用分块追加的方式上传对象

    分块操作

    API 操作名 操作描述
    List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
    Initiate Multipart Upload 初始化分块上传 初始化 Multipart Upload 上传操作
    Upload Part 上传分块 分块上传文件
    List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
    Complete Multipart Upload 完成分块上传 完成整个文件的分块上传
    Abort 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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
        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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
        // 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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
        // 文件夹名称
       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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
        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.tencentcloud.com/cos5/bucket
      // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
              SecretID: os.Getenv("SECRETID"),
              // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
              SecretKey: os.Getenv("SECRETKEY"),
          },
      })
      // 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"),
              SecretKey: os.Getenv("SECRETKEY"),
          },
      })
      // 多线程批量上传文件
      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.tencentcloud.com/cam/capi
              SecretID: os.Getenv("SECRETID"),
              // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
              SecretKey: os.Getenv("SECRETKEY"),
          },
      })
      // 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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
        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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       _, _, 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() {
       // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       name := "exampleobject"
       // 可选opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
       v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
       if err != nil {
           panic(err)
       }
       UploadID := v.UploadID
       fmt.Println(UploadID)
    }
    

    参数说明

    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      int64   
      Expires            string 
      // 自定义的 x-cos-meta-* header
      XCosMetaXXX        *http.Header 
      XCosStorageClass   string      
    }
    
    参数名称 参数描述 类型 是否必填
    key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg string
    XCosACL 设置文件 ACL,例如 private,public-read 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
    ContentDisposition 文件名称,设置 Content-Disposition string
    ContentEncoding 编码格式,设置 Content-Encoding string
    ContentLength 设置传输长度 int64
    XCosMetaXXX 用户自定义的文件元信息, 必须以 x-cos-meta 开头,否则会被忽略 http.Header

    返回结果说明

    type InitiateMultipartUploadResult struct {
      Bucket   string
      Key      string
      UploadID string
    } 
    
    参数名称 参数描述 类型
    UploadId 标识分块上传的 ID string
    Bucket Bucket 名称,由 bucket-appid 组成 string
    Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string

    上传分块

    分块上传对象(Upload Part)。

    方法原型

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

    请求示例

    package main
    import (
       "context"
       "fmt"
       "github.com/tencentyun/cos-go-sdk-v5"
       "net/http"
       "net/url"
       "os"
       "strings"
    )
    func main() {
       // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       name := "exampleobject"
       // 可选opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
       v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
       if err != nil {
           panic(err)
       }
       UploadID := v.UploadID
       fmt.Println(UploadID)
       // 注意,上传分块的块数最多10000块
       key := "exampleobject"
       f := strings.NewReader("test hello")
       // opt可选
       resp, err := client.Object.UploadPart(
           context.Background(), key, UploadID, 1, f, nil,
       )
       if err != nil {
           panic(err)
       }
       PartETag := resp.Header.Get("ETag")
       fmt.Println(PartETag)
    }
    

    参数说明

    type ObjectUploadPartOptions struct {
      ContentLength   int64
      ContentMD5      string
    }
    
    参数名称 参数描述 类型 是否必填
    key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
    UploadId 标识分块上传的 ID,由 InitiateMultipartUpload 生成 string
    PartNumber 标识上传分块的序号 int
    r 上传分块的内容,可以为本地文件流或输入流。当 r 不是bytes.Buffer/bytes.Reader/strings.Reader时,必须指定 opt.ContentLength io.Reader
    ContentLength 设置传输长度 int64
    ContentMD5 RFC 1864中定义的请求体内容的16字节二进制 MD5 哈希值的 Base64 编码形式,用于完整性检查,验证请求体在传输过程中是否发生变化,最终的取值长度应为24个字符,请注意在编写代码时使用正确的方法和参数,例如ZzD3iDJdrMAAb00lgLLeig== string

    返回结果说明

    {
      'ETag': 'string'
    }
    

    通过返回结果Response获取。

    resp, err := client.Object.UploadPart(context.Background(), key, UploadID, 1, f, nil)
    etag := resp.Header.Get("ETag")
    
    参数名称 参数描述 类型
    ETag 上传分块的 MD5 值 string

    查询已上传块

    功能说明

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

    方法原型

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

    请求示例

    package main                                                                                                                                                                                   
    import (
       "context"
       "fmt"
       "github.com/tencentyun/cos-go-sdk-v5"
       "net/http"
       "net/url"
       "os"
    )
    func main() {
       // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       key := "exampleobject"
       v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)
       if err != nil {
           panic(err)
       }
       UploadID := v.UploadID
       fmt.Println(UploadID)
       _, _, err = client.Object.ListParts(context.Background(), key, UploadID, nil)
       if err != nil {
           panic(err)
       }
    }
    

    参数说明

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

    返回结果说明

    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
    }
    
    参数名称 参数描述 类型
    Bucket 存储桶名称,格式:BucketName-APPID。例如 examplebucket-1250000000 string
    EncodingType 默认不编码,规定返回值的编码方式,可选值:url string
    Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
    UploadId 标识分块上传的 ID,由 InitiateMultipartUpload 生成 string
    Initiator 分块上传的创建者,包括 DisplayName,UIN 和 ID struct
    Owner 文件拥有者的信息,包括 DisplayName ,UIN 和 ID struct
    StorageClass 文件的存储类型,例如 STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD。更多存储类型,请参见 存储类型概述 string
    PartNumberMarker 默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出 string
    NextPartNumberMarker 指明下一次列出分块的起始位置 string
    MaxParts 最多返回的分块的数量,默认为最大的1000 string
    IsTruncated 表示返回的分块是否被截断 bool
    Part 上传分块的相关信息,包括 ETag,PartNumber,Size,LastModified struct

    完成分块上传

    功能说明

    完成整个文件的分块上传(Complete Multipart Upload)。

    方法原型

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

    请求示例

    package main
    import (
       "context"
       "fmt"
       "github.com/tencentyun/cos-go-sdk-v5"
       "net/http"
       "net/url"
       "os"
       "strings"
    )
    func main() {
       // 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       name := "exampleobject"
       // 可选opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
       v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
       if err != nil {
           panic(err)
       }
       UploadID := v.UploadID
       fmt.Println(UploadID)
       // 注意,上传分块的块数最多10000块
       key := "exampleobject"
       f := strings.NewReader("test hello")
       // opt可选
       resp, err := client.Object.UploadPart(
           context.Background(), key, UploadID, 1, f, nil,
       )
       if err != nil {
           panic(err)
       }
       PartETag := resp.Header.Get("ETag")
       fmt.Println(PartETag)
        opt := &cos.CompleteMultipartUploadOptions{}
       opt.Parts = append(opt.Parts, cos.Object{
           PartNumber: 1, ETag: PartETag},
       )
       _, _, err = client.Object.CompleteMultipartUpload(
           context.Background(), key, UploadID, opt,
       )
       if err != nil {
           panic(err)
       }
    }
    

    参数说明

    type CompleteMultipartUploadOptions struct {
      Parts   []Object 
    }
    type Object struct { 
      ETag         string 
      PartNumber   int     
    }
    
    参数名称 参数描述 类型 是否必填
    key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
    UploadId 标识分块上传的 ID,由 InitiateMultipartUpload 生成 string
    CompleteMultipartUploadOptions 所有分块的 ETag 和 PartNumber 信息 struct

    返回结果说明

    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

    终止分块上传

    功能说明

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

    方法原型

    func (s *ObjectService) AbortMultipartUpload(ctx context.Context, key, uploadID string) (*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.tencentcloud.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.tencentcloud.com/ ,关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.tencentcloud.com/cam/capi
               SecretKey: os.Getenv("SECRETKEY"),
           },
       })
       key := "exampleobject"
       v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)
       if err != nil {
           panic(err)
       }
       UploadID := v.UploadID
       // Abort
       _, err = client.Object.AbortMultipartUpload(context.Background(), key, UploadID)
       if err != nil {
           panic(err)
       }
    }
    

    参数说明

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

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持