cos

package module
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 18, 2019 License: MIT Imports: 21 Imported by: 15

README

go-cos

腾讯云对象存储服务 COS(Cloud Object Storage) Go SDK（API 版本：V5 版本的 XML API）。

Build Status Coverage Status Go Report Card GoDoc

Install

go get -u github.com/mozillazg/go-cos

推荐使用 go mod 之类的技术指定使用的 go-cos 包版本号。

Usage

package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
	"os"

	"github.com/mozillazg/go-cos"
)

func main() {
	b, _ := cos.NewBaseURL("https://<bucket>-<appid>.cos.<region>.myqcloud.com")
	c := cos.NewClient(b, &http.Client{
		Transport: &cos.AuthorizationTransport{
			SecretID:  os.Getenv("COS_SECRETID"),
			SecretKey: os.Getenv("COS_SECRETKEY"),
		},
	})

	name := "test/hello.txt"
	resp, err := c.Object.Get(context.Background(), name, nil)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	bs, _ := ioutil.ReadAll(resp.Body)
	fmt.Printf("%s\n", string(bs))
}

备注：

  • SDK 不会自动设置超时时间，用户根据需要设置合适的超时时间（比如，设置 http.Client 的 Timeout 字段或者 Transport 字段之类的）或在需要时实现所需的超时机制（比如，通过 context 包实现）。
  • 所有的 API 在 _example 目录下都有对应的使用示例（示例程序中用到的 debug 包只是调试用的不是必需的依赖）。

TODO

Service API:

Bucket API:

Object API:

其他功能：

Documentation

Overview

Package cos 腾讯云对象存储服务 COS(Cloud Object Storage) Go SDK。

COS API Version

封装了 V5 版本的 XML API 。

Usage

在项目的 _example 目录下有各个 API 的使用示例[1] 。

[1]: 示例文件所对应的 API 说明 https://github.com/mozillazg/go-cos#todo

备注

* SDK 不会自动设置超时时间，用户根据需要设置合适的超时时间（比如，设置 `http.Client` 的 `Timeout` 字段或者 `Transport` 字段之类的）或在需要时实现所需的超时机制（比如，通过 `context` 包实现）。

* 所有的 API 在 _example 目录下都有对应的使用示例[1]（示例程序中用到的 `debug` 包只是调试用的不是必需的依赖）。

[1]: 示例文件所对应的 API 说明 https://github.com/mozillazg/go-cos#todo

Authentication

默认所有 API 都是匿名访问. 如果想添加认证信息的话,可以通过自定义一个 http.Client 来添加认证信息.

比如, 使用内置的 AuthorizationTransport 来为请求增加 Authorization Header 签名信息: 

client := cos.NewClient(b, &http.Client{
		Transport: &cos.AuthorizationTransport{
			SecretID:  "COS_SECRETID",
			SecretKey: "COS_SECRETKEY",
		},
	})

Index

Constants

View Source 
const (
	// StorageClassStandard Object 的存储级别: STANDARD
	StorageClassStandard string = "STANDARD"
	// StorageClassStandardTA Object 的存储级别: STANDARD_IA
	StorageClassStandardTA string = "STANDARD_IA"
	// StorageClassArchive Object 的存储级别: ARCHIVE
	StorageClassArchive string = "ARCHIVE"

	// ObjectTypeAppendable : appendable
	ObjectTypeAppendable string = "appendable"
	// ObjectTypeNormal : normal
	ObjectTypeNormal string = "normal"

	// ServerSideEncryptionAES256 服务端加密算法: AES256
	ServerSideEncryptionAES256 string = "AES256"

	// PermissionRead 权限值: READ
	PermissionRead string = "READ"
	// PermissionWrite 权限值: WRITE
	PermissionWrite string = "WRITE"
	// PermissionFullControl  权限值: FULL_CONTROL
	PermissionFullControl string = "FULL_CONTROL"
)
View Source 
const (
	// Version ...
	Version = "0.13.0"
)

Variables

This section is empty.

Functions

func AddAuthorizationHeader added in v0.4.0 

func AddAuthorizationHeader(secretID, secretKey string, req *http.Request, authTime *AuthTime)

AddAuthorizationHeader 给 req 增加签名信息

func NewBucketURL added in v0.3.0 

func NewBucketURL(bucketName, appID, region string, secure bool) *url.URL

NewBucketURL 生成 BaseURL 所需的 BucketURL 

bucketName: bucket 名称
AppID: 应用 ID
Region: 区域代码，详见 https://cloud.tencent.com/document/product/436/6224
secure: 是否使用 https

Types

type ACLGrant added in v0.4.0 

type ACLGrant struct {
	Grantee *ACLGrantee
	// 指明授予被授权者的权限信息，枚举值：READ，WRITE，FULL_CONTROL
	Permission string
}

ACLGrant ...

type ACLGrantee added in v0.4.0 

type ACLGrantee struct {
	Type        string `xml:"type,attr"`
	UIN         string `xml:"uin,omitempty"`
	ID          string `xml:",omitempty"`
	DisplayName string `xml:",omitempty"`
	SubAccount  string `xml:"Subaccount,omitempty"`
}

ACLGrantee ...

type ACLHeaderOptions added in v0.3.0 

type ACLHeaderOptions struct {
	// 定义 Object 的 acl 属性。有效值：private，public-read-write，public-read；默认值：private
	XCosACL string `header:"x-cos-acl,omitempty" url:"-" xml:"-"`
	// 	赋予被授权者读的权限。格式：id="[OwnerUin]"
	XCosGrantRead string `header:"x-cos-grant-read,omitempty" url:"-" xml:"-"`
	// 赋予被授权者写的权限。格式：id="[OwnerUin]"
	XCosGrantWrite string `header:"x-cos-grant-write,omitempty" url:"-" xml:"-"`
	// 赋予被授权者所有的权限。格式：id="[OwnerUin]"
	XCosGrantFullControl string `header:"x-cos-grant-full-control,omitempty" url:"-" xml:"-"`
}

ACLHeaderOptions ...

type ACLXml added in v0.4.0 

type ACLXml struct {
	XMLName           xml.Name `xml:"AccessControlPolicy"`
	Owner             *Owner
	AccessControlList []ACLGrant `xml:"AccessControlList>Grant,omitempty"`
}

ACLXml ...

https://cloud.tencent.com/document/product/436/7733

type Auth added in v0.9.0 

type Auth struct {
	SecretID  string
	SecretKey string
	// 签名多久过期，默认是 time.Hour
	Expire time.Duration
}

Auth 签名相关的认证信息

type AuthTime added in v0.2.0 

type AuthTime struct {
	SignStartTime time.Time
	SignEndTime   time.Time
	KeyStartTime  time.Time
	KeyEndTime    time.Time
}

AuthTime 用于生成签名所需的 q-sign-time 和 q-key-time 相关参数

func NewAuthTime added in v0.2.0 

func NewAuthTime(expire time.Duration) *AuthTime

NewAuthTime 生成 AuthTime 的便捷函数 

expire: 从现在开始多久过期.

type AuthorizationTransport added in v0.4.0 

type AuthorizationTransport struct {
	SecretID  string
	SecretKey string
	// 临时密钥: https://cloud.tencent.com/document/product/436/14048
	SessionToken string
	// 签名多久过期，默认是 time.Hour
	Expire time.Duration

	// 实际发送 http 请求的 http.RoundTripper，默认使用 http.DefaultTransport
	Transport http.RoundTripper
}

AuthorizationTransport 给请求增加 Authorization header

func (*AuthorizationTransport) RoundTrip added in v0.4.0 

func (t *AuthorizationTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements the RoundTripper interface.

type BaseURL added in v0.3.0 

type BaseURL struct {
	// 访问 bucket, object 相关 API 的基础 URL（不包含 path 部分）
	// 比如：https://test-1253846586.cos.ap-beijing.myqcloud.com
	// 详见 https://cloud.tencent.com/document/product/436/6224
	BucketURL *url.URL
	// 访问 service API 的基础 URL（不包含 path 部分）
	// 比如：https://service.cos.myqcloud.com
	ServiceURL *url.URL
}

BaseURL 访问各 API 所需的基础 URL

func NewBaseURL added in v0.8.0 

func NewBaseURL(bucketURL string) (u *BaseURL, err error)

NewBaseURL 生成 BaseURL

type Bucket 

type Bucket struct {
	Name       string
	AppID      string `xml:",omitempty"`
	Region     string `xml:"Location,omitempty"`
	CreateDate string `xml:"CreationDate,omitempty"`
}

Bucket ...

type BucketCORSRule 

type BucketCORSRule struct {
	// 配置规则的 ID
	ID string `xml:"ID,omitempty"`
	// 允许的 HTTP 操作，枚举值：GET，PUT，HEAD，POST，DELETE
	AllowedMethods []string `xml:"AllowedMethod"`
	// 允许的访问来源，支持通配符 * 格式为：协议://域名[:端口] 如：http://www.qq.com
	AllowedOrigins []string `xml:"AllowedOrigin"`
	// 在发送 OPTIONS 请求时告知服务端，接下来的请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *
	AllowedHeaders []string `xml:"AllowedHeader,omitempty"`
	// 设置 OPTIONS 请求得到结果的有效期
	MaxAgeSeconds int `xml:"MaxAgeSeconds,omitempty"`
	// 设置浏览器可以接收到的来自服务器端的自定义头部信息
	ExposeHeaders []string `xml:"ExposeHeader,omitempty"`
}

BucketCORSRule ...

https://cloud.tencent.com/document/product/436/8279

type BucketGetACLResult added in v0.3.0 

type BucketGetACLResult ACLXml

BucketGetACLResult ...

https://cloud.tencent.com/document/product/436/7733

type BucketGetCORSResult added in v0.3.0 

type BucketGetCORSResult struct {
	XMLName xml.Name `xml:"CORSConfiguration"`
	// 说明跨域资源共享配置的所有信息，最多可以包含100条 CORSRule
	Rules []BucketCORSRule `xml:"CORSRule,omitempty"`
}

BucketGetCORSResult ...

https://cloud.tencent.com/document/product/436/8274

type BucketGetLifecycleResult added in v0.3.0 

type BucketGetLifecycleResult struct {
	XMLName xml.Name              `xml:"LifecycleConfiguration"`
	Rules   []BucketLifecycleRule `xml:"Rule,omitempty"`
}

BucketGetLifecycleResult ...

https://cloud.tencent.com/document/product/436/8278

type BucketGetLocationResult added in v0.3.0 

type BucketGetLocationResult struct {
	XMLName xml.Name `xml:"LocationConstraint"`
	// 说明 Bucket 所在地域，枚举值参见 可用地域[1] 文档，如：ap-beijing、ap-hongkong、eu-frankfurt 等
	// [1]: https://cloud.tencent.com/document/product/436/6224
	Location string `xml:",chardata"`
}

BucketGetLocationResult ...

type BucketGetOptions 

type BucketGetOptions struct {
	// 前缀匹配，用来规定返回的文件前缀地址
	Prefix string `url:"prefix,omitempty"`
	// 定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，
	// 定义为 Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始
	Delimiter string `url:"delimiter,omitempty"`
	// 规定返回值的编码方式，可选值：url
	EncodingType string `url:"encoding-type,omitempty"`
	// 默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始
	Marker string `url:"marker,omitempty"`
	// 单次返回最大的条目数量，默认 1000
	MaxKeys int `url:"max-keys,omitempty"`
}

BucketGetOptions 请求参数

https://cloud.tencent.com/document/product/436/7734

type BucketGetResult added in v0.3.0 

type BucketGetResult struct {
	XMLName xml.Name `xml:"ListBucketResult"`
	// 说明 Bucket 的信息
	Name string
	// 前缀匹配，用来规定响应请求返回的文件前缀地址
	Prefix string `xml:"Prefix,omitempty"`
	// 默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始
	Marker string `xml:"Marker,omitempty"`
	// 假如返回条目被截断，则返回 NextMarker 就是下一个条目的起点
	NextMarker string `xml:"NextMarker,omitempty"`
	// 定界符，见 BucketGetOptions.Delimiter
	Delimiter string `xml:"Delimiter,omitempty"`
	// 单次响应请求内返回结果的最大的条目数量
	MaxKeys int
	// 响应请求条目是否被截断，布尔值：true，false
	IsTruncated bool
	// 元数据信息
	Contents []Object `xml:"Contents,omitempty"`
	// 将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix
	CommonPrefixes []string `xml:"CommonPrefixes>Prefix,omitempty"`
	// 编码格式
	EncodingType string `xml:"Encoding-Type,omitempty"`
}

BucketGetResult 响应结果

https://cloud.tencent.com/document/product/436/7734

type BucketGetTaggingResult added in v0.3.0 

type BucketGetTaggingResult struct {
	XMLName xml.Name           `xml:"Tagging"`
	TagSet  []BucketTaggingTag `xml:"TagSet>Tag,omitempty"`
}

BucketGetTaggingResult ...

type BucketLifecycleAbortIncompleteMultipartUpload 

type BucketLifecycleAbortIncompleteMultipartUpload struct {
	// 指明分片上传开始后多少天内必须完成上传
	DaysAfterInitiation int `xml:"DaysAfterInitiation,omitempty"`
}

BucketLifecycleAbortIncompleteMultipartUpload ...

type BucketLifecycleExpiration 

type BucketLifecycleExpiration struct {
	// 指明规则对应的动作在何时操作
	Date string `xml:"Date,omitempty"`
	// 指明规则对应的动作在对象最后的修改日期过后多少天操作，该字段有效值为正整数
	Days int `xml:"Days,omitempty"`
	// 删除过期对象删除标记，枚举值 true，false
	ExpiredObjectDeleteMarker bool `xml:"ExpiredObjectDeleteMarker,omitempty"`
	// 指明规则对应的动作在对象变成非当前版本多少天后执行，该字段有效值是正整数
	// 只在作为 NoncurrentVersionExpiration 字段的值时有效
	NoncurrentDays int
}

BucketLifecycleExpiration ...

type BucketLifecycleFilter added in v0.11.0 

type BucketLifecycleFilter struct {
	// 指定规则所适用的前缀。匹配前缀的对象受该规则影响，Prefix 最多只能有一个
	Prefix string                 `xml:"Prefix,omitempty"`
	And    *BucketLifecycleFilter `xml:"And,omitempty"`
}

BucketLifecycleFilter ...

type BucketLifecycleRule 

type BucketLifecycleRule struct {
	// 用于唯一地标识规则，长度不能超过 255 个字符
	ID string `xml:"ID,omitempty"`
	// Filter 用于描述规则影响的 Object 集合
	Filter *BucketLifecycleFilter
	// 已废弃，改为使用 Filter
	Prefix string
	// 指明规则是否启用，枚举值：Enabled，Disabled
	Status string
	// 规则转换属性，对象何时转换为 Standard_IA 或 Archive
	Transition *BucketLifecycleTransition `xml:"Transition,omitempty"`
	// 规则过期属性
	Expiration *BucketLifecycleExpiration `xml:"Expiration,omitempty"`
	// 设置允许分片上传保持运行的最长时间
	AbortIncompleteMultipartUpload *BucketLifecycleAbortIncompleteMultipartUpload `xml:"AbortIncompleteMultipartUpload,omitempty"`
	// 指明非当前版本对象何时过期
	NoncurrentVersionExpiration *BucketLifecycleExpiration `xml:"NoncurrentVersionExpiration,omitempty"`
	// 指明非当前版本对象何时转换为 STANDARD_IA 或 ARCHIVE
	NoncurrentVersionTransition *BucketLifecycleTransition `xml:"NoncurrentVersionTransition,omitempty"`
}

BucketLifecycleRule ...

https://cloud.tencent.com/document/product/436/8280

type BucketLifecycleTransition 

type BucketLifecycleTransition struct {
	// 指明规则对应的动作在何时操作
	Date string `xml:"Date,omitempty"`
	// 指明规则对应的动作在对象最后的修改日期过后多少天操作，该字段有效值是非负整数
	Days int `xml:"Days,omitempty"`
	// 指定 Object 转储到的目标存储类型，枚举值： STANDARD_IA, ARCHIVE
	StorageClass string
	// 指明规则对应的动作在对象变成非当前版本多少天后执行，该字段有效值是非负整数
	// 只在作为 NoncurrentVersionTransition 字段的值时有效
	NoncurrentDays int
}

BucketLifecycleTransition ...

type BucketPutACLOptions 

type BucketPutACLOptions struct {
	Header *ACLHeaderOptions `url:"-" xml:"-"`
	Body   *ACLXml           `url:"-" header:"-"`
}

BucketPutACLOptions ... Header 和 Body 二选一

type BucketPutCORSOptions added in v0.3.0 

type BucketPutCORSOptions struct {
	XMLName xml.Name `xml:"CORSConfiguration"`
	// 说明跨域资源共享配置的所有信息，最多可以包含 100 条 CORSRule
	Rules []BucketCORSRule `xml:"CORSRule,omitempty"`
}

BucketPutCORSOptions ...

https://cloud.tencent.com/document/product/436/8279

type BucketPutLifecycleOptions added in v0.3.0 

type BucketPutLifecycleOptions struct {
	XMLName xml.Name              `xml:"LifecycleConfiguration"`
	Rules   []BucketLifecycleRule `xml:"Rule,omitempty"`
}

BucketPutLifecycleOptions ...

type BucketPutOptions 

type BucketPutOptions ACLHeaderOptions

BucketPutOptions ...

type BucketPutTaggingOptions added in v0.3.0 

type BucketPutTaggingOptions struct {
	XMLName xml.Name           `xml:"Tagging"`
	TagSet  []BucketTaggingTag `xml:"TagSet>Tag,omitempty"`
}

BucketPutTaggingOptions ...

type BucketService 

type BucketService service

BucketService ...

Bucket 相关 API

func (*BucketService) Delete 

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

Delete Bucket 请求可以确认该 Bucket 是否存在，是否有权限访问。HEAD 的权限与 Read 一致。 当该 Bucket 存在时，返回 HTTP 状态码 200；当该 Bucket 无访问权限时，返回 HTTP 状态码 403； 当该 Bucket 不存在时，返回 HTTP 状态码 404。

注意： 目前还没有公开获取 Bucket 属性的接口（即可以返回 acl 等信息）。

https://cloud.tencent.com/document/product/436/7735

func (*BucketService) DeleteCORS 

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

DeleteCORS ...

Delete Bucket CORS 接口请求实现删除跨域访问配置信息。

https://cloud.tencent.com/document/product/436/8283

func (*BucketService) DeleteLifecycle 

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

DeleteLifecycle ...

Delete Bucket Lifecycle 用来删除 Bucket 的生命周期配置。

https://cloud.tencent.com/document/product/436/8284

func (*BucketService) DeleteTagging 

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

DeleteTagging ...

Delete Bucket Tagging接口实现删除指定Bucket的标签。

https://www.qcloud.com/document/product/436/8286

func (*BucketService) Get 

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

Get Bucket 请求等同于 List Object请求，可以列出该 Bucket 下的部分或者全部 Object。 此 API 调用者需要对 Bucket 有 Read 权限。

https://cloud.tencent.com/document/product/436/7734

func (*BucketService) GetACL 

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

GetACL 接口用来获取存储桶的访问权限控制列表。

https://cloud.tencent.com/document/product/436/7733

func (*BucketService) GetCORS 

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

GetCORS ...

Get Bucket CORS 接口实现 Bucket 持有者在 Bucket 上进行跨域资源共享的信息配置。 （cors 是一个 W3C 标准，全称是"跨域资源共享"（Cross-origin resource sharing））。 默认情况下，Bucket 的持有者直接有权限使用该 API 接口，Bucket 持有者也可以将权限授予其他用户。

https://cloud.tencent.com/document/product/436/8274

func (*BucketService) GetLifecycle 

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

GetLifecycle ...

Get Bucket Lifecycle 用来查询 Bucket 的生命周期配置。

https://cloud.tencent.com/document/product/436/8278

func (*BucketService) GetLocation 

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

GetLocation ...

Get Bucket Location 接口用于获取 Bucket 所在的地域信息，该 GET 操作使用 location 参数返回 Bucket 所在的区域， 只有 Bucket 持有者才有该 API 接口的操作权限。

https://cloud.tencent.com/document/product/436/8275

func (*BucketService) GetTagging 

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

GetTagging ...

Get Bucket Tagging接口实现获取指定Bucket的标签。

https://www.qcloud.com/document/product/436/8277

func (*BucketService) Head 

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

Head Bucket请求可以确认是否存在该Bucket，是否有权限访问，Head的权限与Read一致。 

当其存在时，返回 HTTP 状态码200；
当无权限时，返回 HTTP 状态码403；
当不存在时，返回 HTTP 状态码404。

https://www.qcloud.com/document/product/436/7735

func (*BucketService) ListMultipartUploads 

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

ListMultipartUploads ...

List Multipart Uploads 用来查询正在进行中的分块上传。单次请求操作最多列出 1000 个正在进行中的分块上传。

注意：该请求需要有 Bucket 的读权限。

https://cloud.tencent.com/document/product/436/7736

func (*BucketService) Put 

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

Put Bucket 接口请求可以在指定账号下创建一个 Bucket。该 API 接口不支持匿名请求， 您需要使用帯 Authorization 签名认证的请求才能创建新的 Bucket 。 创建 Bucket 的用户默认成为 Bucket 的持有者。

细节分析

创建 Bucket 时，如果没有指定访问权限，则默认使用私有读写（private）权限。

https://cloud.tencent.com/document/product/436/7738

func (*BucketService) PutACL 

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

PutACL 使用API写入Bucket的ACL表

Put Bucket ACL 是一个覆盖操作，传入新的ACL将覆盖原有ACL。只有所有者有权操作。

私有 Bucket 可以下可以给某个文件夹设置成公有，那么该文件夹下的文件都是公有； 但是把文件夹设置成私有后，在该文件夹中设置的公有属性，不会生效。

https://cloud.tencent.com/document/product/436/7737

func (*BucketService) PutCORS 

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

PutCORS ...

Put Bucket CORS 接口用来请求设置 Bucket 的跨域资源共享权限，。 默认情况下，Bucket 的持有者直接有权限使用该 API 接口，Bucket 持有者也可以将权限授予其他用户。

https://cloud.tencent.com/document/product/436/8279

func (*BucketService) PutLifecycle 

func (s *BucketService) PutLifecycle(ctx context.Context, opt *BucketPutLifecycleOptions) (*Response, error)

PutLifecycle ...

COS 支持用户以生命周期配置的方式来管理 Bucket 中 Object 的生命周期。 生命周期配置包含一个或多个将应用于一组对象规则的规则集 (其中每个规则为 COS 定义一个操作)。

这些操作分为以下两种：

转换操作：定义对象转换为另一个存储类的时间。例如，您可以选择在对象创建 30 天后将其转换为低频存储（STANDARD_IA，适用于不常访问) 

存储类别。同时也支持将数据沉降到归档存储（Archive，成本更低，目前支持国内园区）。具体参数参见请求示例说明中 Transition 项。

过期操作：指定 Object 的过期时间。COS 将会自动为用户删除过期的 Object。

细节分析

PUT Bucket lifecycle 用于为 Bucket 创建一个新的生命周期配置。如果该 Bucket 已配置生命周期， 使用该接口创建新的配置的同时则会覆盖原有的配置。

https://cloud.tencent.com/document/product/436/8280

func (*BucketService) PutTagging 

func (s *BucketService) PutTagging(ctx context.Context, opt *BucketPutTaggingOptions) (*Response, error)

PutTagging ...

Put Bucket Tagging接口实现给用指定Bucket打标签。用来组织和管理相关Bucket。

当该请求设置相同Key名称，不同Value时，会返回400。请求成功，则返回204。

https://www.qcloud.com/document/product/436/8281

type BucketTaggingTag 

type BucketTaggingTag struct {
	Key   string
	Value string
}

BucketTaggingTag ...

type Caller added in v0.12.0 

type Caller struct {
	// 调用的方法名称
	Method MethodName
}

Caller 方法调用信息，用于 Sender 和 ResponseParser 中判断是来自哪个方法的调用

type Client 

type Client struct {
	// Sender 用于实际发送 HTTP 请求
	Sender Sender
	// ResponseParser 用于解析响应
	ResponseParser ResponseParser

	UserAgent string
	BaseURL   *BaseURL

	// Service 封装了 service 相关的 API
	Service *ServiceService
	// Bucket 封装了 bucket 相关的 API
	Bucket *BucketService
	// Object 封装了 object 相关的 API
	Object *ObjectService
	// contains filtered or unexported fields
}

A Client manages communication with the COS API.

func NewClient 

func NewClient(uri *BaseURL, httpClient *http.Client) *Client

NewClient returns a new COS API client. 使用 DefaultSender 作为 Sender，DefaultResponseParser 作为 ResponseParser

type CompleteMultipartUploadOptions added in v0.4.0 

type CompleteMultipartUploadOptions struct {
	XMLName xml.Name `xml:"CompleteMultipartUpload"`
	Parts   []Object `xml:"Part"`
}

CompleteMultipartUploadOptions ...

https://cloud.tencent.com/document/product/436/7742

type CompleteMultipartUploadResult added in v0.4.0 

type CompleteMultipartUploadResult struct {
	XMLName xml.Name `xml:"CompleteMultipartUploadResult"`
	// 创建的Object的外网访问域名
	Location string
	// 分块上传的目标Bucket，由用户自定义字符串和系统生成appid数字串由中划线连接而成，
	// 如：mybucket-1250000000
	Bucket string
	// Object的名称
	Key string
	// 合并后对象的唯一标签值，该值不是对象内容的 MD5 校验值，仅能用于检查对象唯一性
	ETag string
}

CompleteMultipartUploadResult ...

https://cloud.tencent.com/document/product/436/7742

type DefaultResponseParser added in v0.12.0 

type DefaultResponseParser struct{}

DefaultResponseParser 是默认的 ResponseParser 实现

func (*DefaultResponseParser) ParseResponse added in v0.12.0 

func (p *DefaultResponseParser) ParseResponse(ctx context.Context, caller Caller, resp *http.Response, result interface{}) (*Response, error)

ParseResponse 解析响应内容，反序列化后的结果将存储在指针类型的 result 中

type DefaultSender added in v0.12.0 

type DefaultSender struct {
	*http.Client
}

DefaultSender 是基于 http.Client 的默认 Sender 实现

func (*DefaultSender) Send added in v0.12.0 

func (s *DefaultSender) Send(ctx context.Context, caller Caller, req *http.Request) (*http.Response, error)

Send 发送 http 请求

type ErrorResponse 

type ErrorResponse struct {
	XMLName xml.Name `xml:"Error"`
	// TODO: use cos.Response instead
	Response  *http.Response `xml:"-"`
	Code      string
	Message   string
	Resource  string
	RequestID string `xml:"RequestId"`
	TraceID   string `xml:"TraceId,omitempty"`
}

ErrorResponse 包含 COS HTTP API 返回的错误信息

https://cloud.tencent.com/document/product/436/7730

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

Error ...

type InitiateMultipartUploadOptions added in v0.4.0 

type InitiateMultipartUploadOptions struct {
	*ACLHeaderOptions
	*ObjectPutHeaderOptions
}

InitiateMultipartUploadOptions ...

type InitiateMultipartUploadResult added in v0.4.0 

type InitiateMultipartUploadResult struct {
	XMLName xml.Name `xml:"InitiateMultipartUploadResult"`
	// 分片上传的目标 Bucket，由用户自定义字符串和系统生成appid数字串由中划线连接而成，如：mybucket-1250000000
	Bucket string
	// Object 的名称
	Key string
	// 在后续上传中使用的 ID
	UploadID string `xml:"UploadId"`
}

InitiateMultipartUploadResult ...

type Initiator 

type Initiator Owner

Initiator ...

type ListMultipartUploadsOptions 

type ListMultipartUploadsOptions struct {
	// https://cloud.tencent.com/document/product/436/7736
	Delimiter string `url:"delimiter,omitempty"`
	// 规定返回值的编码格式，合法值：url
	EncodingType string `url:"encoding-type,omitempty"`
	// 限定返回的 Object key 必须以 Prefix 作为前缀。
	// 注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix
	Prefix string `url:"prefix,omitempty"`
	// 设置最大返回的 multipart 数量，合法取值从1到1000，默认1000
	MaxUploads int `url:"max-uploads,omitempty"`
	// 与 UploadIDMarker 一起使用
	// 当 UploadIDMarker 未被指定时，ObjectName 字母顺序大于 KeyMarker 的条目将被列出
	// 当 UploadIDMarker 被指定时，ObjectName 字母顺序大于 KeyMarker 的条目被列出，
	// ObjectName 字母顺序等于 KeyMarker 同时 UploadID 大于 UploadIDMarker 的条目将被列出。
	KeyMarker      string `url:"key-marker,omitempty"`
	UploadIDMarker string `url:"upload-id-marker,omitempty"`
}

ListMultipartUploadsOptions ...

https://cloud.tencent.com/document/product/436/7736

type ListMultipartUploadsResult 

type ListMultipartUploadsResult struct {
	XMLName xml.Name `xml:"ListMultipartUploadsResult"`
	// 分块上传的目标 Bucket,由用户自定义字符串和系统生成appid数字串由中划线连接而成，
	// 如：mybucket-1250000000
	Bucket string `xml:"Bucket"`
	// 规定返回值的编码格式，合法值：url
	EncodingType string `xml:"Encoding-Type"`
	// 列出条目从该 key 值开始
	KeyMarker string
	// 列出条目从该 UploadId 值开始
	UploadIDMarker string `xml:"UploadIdMarker"`
	// 假如返回条目被截断，则返回 NextKeyMarker 就是下一个条目的起点
	NextKeyMarker string
	// 假如返回条目被截断，则返回 UploadId 就是下一个条目的起点
	NextUploadIDMarker string `xml:"NextUploadIdMarker"`
	// 设置最大返回的 multipart 数量，合法取值从 0 到 1000
	MaxUploads int
	// 返回条目是否被截断
	IsTruncated bool
	// Upload 列表
	Uploads []MultipartUpload `xml:"Upload,omitempty"`
	// 限定返回的 Object key 必须以 Prefix 作为前缀。
	// 注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix
	Prefix string
	// 定界符为一个符号，对 object 名字包含指定前缀且第一次出现 delimiter 字符之间的
	// object 作为一组元素：common prefix。如果没有 prefix，则从路径起点开始
	Delimiter string `xml:"delimiter,omitempty"`
	// 将 prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix
	CommonPrefixes []string `xml:"CommonPrefixs>Prefix,omitempty"`
}

ListMultipartUploadsResult ...

https://cloud.tencent.com/document/product/436/7736

type MethodName added in v0.12.0 

type MethodName string

MethodName 用于 Caller 中表示调用的是哪个方法 

const MethodBucketDelete MethodName = "Bucket.Delete"

MethodBucketDelete method name of Bucket.Delete 

const MethodBucketDeleteCORS MethodName = "Bucket.DeleteCORS"

MethodBucketDeleteCORS method name of Bucket.DeleteCORS 

const MethodBucketDeleteLifecycle MethodName = "Bucket.DeleteLifecycle"

MethodBucketDeleteLifecycle method name of Bucket.DeleteLifecycle 

const MethodBucketGet MethodName = "Bucket.Get"

MethodBucketGet method name of Bucket.Get 

const MethodBucketGetACL MethodName = "Bucket.GetACL"

MethodBucketGetACL method name of Bucket.GetACL 

const MethodBucketGetCORS MethodName = "Bucket.GetCORS"

MethodBucketGetCORS method name of Bucket.GetCORS 

const MethodBucketGetLifecycle MethodName = "Bucket.GetLifecycle"

MethodBucketGetLifecycle method name of Bucket.GetLifecycle 

const MethodBucketGetLocation MethodName = "Bucket.GetLocation"

MethodBucketGetLocation method name of Bucket.GetLocation 

const MethodBucketHead MethodName = "Bucket.Head"

MethodBucketHead method name of Bucket.Head 

const MethodBucketListMultipartUploads MethodName = "Bucket.ListMultipartUploads"

MethodBucketListMultipartUploads method name of Bucket.ListMultipartUploads 

const MethodBucketPut MethodName = "Bucket.Put"

MethodBucketPut method name of Bucket.Put 

const MethodBucketPutACL MethodName = "Bucket.PutACL"

MethodBucketPutACL method name of Bucket.PutACL 

const MethodBucketPutCORS MethodName = "Bucket.PutCORS"

MethodBucketPutCORS method name of Bucket.PutCORS 

const MethodBucketPutLifecycle MethodName = "Bucket.PutLifecycle"

MethodBucketPutLifecycle method name of Bucket.PutLifecycle 

const MethodDeleteTagging MethodName = "Bucket.DeleteTagging"

MethodDeleteTagging method name of Bucket.DeleteTagging 

const MethodGetTagging MethodName = "Bucket.GetTagging"

MethodGetTagging method name of Bucket.GetTagging 

const MethodObjectAbortMultipartUpload MethodName = "Object.AbortMultipartUpload"

MethodObjectAbortMultipartUpload method name of Object.AbortMultipartUpload 

const MethodObjectAppend MethodName = "Object.Append"

MethodObjectAppend method name of Object.Append 

const MethodObjectCompleteMultipartUpload MethodName = "Object.CompleteMultipartUpload"

MethodObjectCompleteMultipartUpload method name of Object.CompleteMultipartUpload 

const MethodObjectCopy MethodName = "Object.Copy"

MethodObjectCopy method name of Object.Copy 

const MethodObjectDelete MethodName = "Object.Delete"

MethodObjectDelete method name of Object.Delete 

const MethodObjectDeleteMulti MethodName = "Object.DeleteMulti"

MethodObjectDeleteMulti method name of Object.DeleteMulti 

const MethodObjectGet MethodName = "Object.Get"

MethodObjectGet method name of Object.Get 

const MethodObjectGetACL MethodName = "Object.GetACL"

MethodObjectGetACL method name of Object.GetACL 

const MethodObjectHead MethodName = "Object.Head"

MethodObjectHead method name of Object.Head 

const MethodObjectInitiateMultipartUpload MethodName = "Object.InitiateMultipartUpload"

MethodObjectInitiateMultipartUpload method name of Object.InitiateMultipartUpload 

const MethodObjectListParts MethodName = "Object.ListParts"

MethodObjectListParts method name of Object.ListParts 

const MethodObjectListPartsWithOpt MethodName = "Object.ListPartsWithOpt"

MethodObjectListPartsWithOpt method name of Object.ListPartsWithOpt 

const MethodObjectOptions MethodName = "Object.Options"

MethodObjectOptions method name of Object.Options 

const MethodObjectPut MethodName = "Object.Put"

MethodObjectPut method name of Object.Put 

const MethodObjectPutACL MethodName = "Object.PutACL"

MethodObjectPutACL method name of Object.PutACL 

const MethodObjectUploadPart MethodName = "Object.UploadPart"

MethodObjectUploadPart method name of Object.UploadPart 

const MethodPutTagging MethodName = "Bucket.PutTagging"

MethodPutTagging method name of Bucket.PutTagging 

const MethodServiceGet MethodName = "Service.Get"

MethodServiceGet method name of Service.Get

type MultipartUpload added in v0.11.0 

type MultipartUpload struct {
	// Object 的名称
	Key string
	// 标示本次分块上传的 ID
	UploadID string `xml:"UploadID"`
	// 用来表示分块的存储级别，枚举值：STANDARD，STANDARD_IA，ARCHIVE
	StorageClass string
	// 用来表示本次上传发起者的信息
	Initiator *Initiator
	// 用来表示这些分块所有者的信息
	Owner *Owner
	// 分块上传的起始时间
	Initiated string
}

MultipartUpload 每个 Multipart Upload 的信息

type Object added in v0.4.0 

type Object struct {
	// Object 的 Key
	Key string `xml:",omitempty"`
	// 文件的 MD-5 算法校验值
	ETag string `xml:",omitempty"`
	// 说明文件大小，单位是 Byte
	Size int `xml:",omitempty"`
	// 块编号
	PartNumber int `xml:",omitempty"`
	// 说明 Object 最后被修改时间
	LastModified string `xml:",omitempty"`
	// Object 的存储级别，枚举值：STANDARD，STANDARD_IA，ARCHIVE
	StorageClass string `xml:",omitempty"`
	// Bucket 持有者信息
	Owner *Owner `xml:",omitempty"`
}

Object ...

type ObjectCopyHeaderOptions added in v0.7.0 

type ObjectCopyHeaderOptions struct {
	// 是否拷贝源文件的元数据，枚举值：Copy, Replaced，默认值 Copy。假如标记为 Copy，
	// 则拷贝源文件的元数据；假如标记为 Replaced，则按本次请求的 Header 信息修改元数据。
	// 当目标路径和源路径一致，即用户试图修改元数据时，则标记必须为 Replaced。
	XCosMetadataDirective string `header:"x-cos-metadata-directive,omitempty" url:"-" xml:"-"`
	// 当 Object 在指定时间后被修改，则执行操作，否则返回 412。
	// 可与 XCosCopySourceIfNoneMatch 一起使用，与其他条件联合使用返回冲突。
	XCosCopySourceIfModifiedSince string `header:"x-cos-copy-source-If-Modified-Since,omitempty" url:"-" xml:"-"`
	// 当 Object 在指定时间后未被修改，则执行操作，否则返回 412。
	// 可与 XCosCopySourceIfMatch 一起使用，与其他条件联合使用返回冲突。
	XCosCopySourceIfUnmodifiedSince string `header:"x-cos-copy-source-If-Unmodified-Since,omitempty" url:"-" xml:"-"`
	// 当 Object 的 Etag 和给定一致时，则执行操作，否则返回 412。
	// 可与 XCosCopySourceIfUnmodifiedSince 一起使用，与其他条件联合使用返回冲突。
	XCosCopySourceIfMatch string `header:"x-cos-copy-source-If-Match,omitempty" url:"-" xml:"-"`
	// 当 Object 的 Etag 和给定不一致时，则执行操作，否则返回 412。
	// 可与 XCosCopySourceIfModifiedSince 一起使用，与其他条件联合使用返回冲突。
	XCosCopySourceIfNoneMatch string `header:"x-cos-copy-source-If-None-Match,omitempty" url:"-" xml:"-"`
	// 设置 Object 的存储级别，枚举值：STANDARD，STANDARD_IA。默认值：STANDARD
	XCosStorageClass string `header:"x-cos-storage-class,omitempty" url:"-" xml:"-"`
	// 自定义的 x-cos-meta-* header
	XCosMetaXXX *http.Header `header:"x-cos-meta-*,omitempty" url:"-"`
	// 源文件 URL 路径，可以通过 versionid 子资源指定历史版本
	XCosCopySource string `header:"x-cos-copy-source" url:"-" xml:"-"`

	// XCosServerSideEncryption 用于指定腾讯云 COS 在数据存储时，应用数据加密的保护策略。
	// 腾讯云 COS 会帮助您在数据写入数据中心时自动加密，并在您取用该数据时自动解密。
	// 目前支持使用腾讯云 COS 主密钥对数据进行 AES-256 加密。
	// 如果您需要对数据启用服务端加密，则需指定 XCosServerSideEncryption。
	//
	// 指定将对象启用服务端加密的方式。使用 COS 主密钥加密填写：AES256
	XCosServerSideEncryption string `header:"x-cos-server-side-encryption,omitempty" url:"-"`
}

ObjectCopyHeaderOptions ... https://cloud.tencent.com/document/product/436/10881

type ObjectCopyOptions added in v0.7.0 

type ObjectCopyOptions struct {
	*ObjectCopyHeaderOptions `header:",omitempty" url:"-" xml:"-"`
	*ACLHeaderOptions        `header:",omitempty" url:"-" xml:"-"`
}

ObjectCopyOptions ...

https://cloud.tencent.com/document/product/436/10881

type ObjectCopyResult added in v0.7.0 

type ObjectCopyResult struct {
	XMLName xml.Name `xml:"CopyObjectResult"`
	// 返回文件的 MD5 算法校验值。ETag 的值可以用于检查 Object 的内容是否发生变化。
	ETag string `xml:"ETag,omitempty"`
	// 返回文件最后修改时间，GMT 格式
	LastModified string `xml:"LastModified,omitempty"`
}

ObjectCopyResult ...

type ObjectDeleteMultiOptions added in v0.3.0 

type ObjectDeleteMultiOptions struct {
	XMLName xml.Name `xml:"Delete" header:"-"`
	// 布尔值，这个值决定了是否启动 Quiet 模式。
	// 值为 true 启动 Quiet 模式，值为 false 则启动 Verbose 模式，默认值为 False
	Quiet bool `xml:"Quiet" header:"-"`
	// 说明每个将要删除的目标 Object 信息，只需指定 Key 即可
	Objects []Object `xml:"Object" header:"-"`
}

ObjectDeleteMultiOptions ...

https://cloud.tencent.com/document/product/436/8289

type ObjectDeleteMultiResult added in v0.3.0 

type ObjectDeleteMultiResult struct {
	XMLName xml.Name `xml:"DeleteResult"`
	// 说明本次删除的成功 Object 信息
	DeletedObjects []Object `xml:"Deleted,omitempty"`
	// 说明本次删除的失败 Object 信息
	Errors []struct {
		// 删除失败的 Object 的名称
		Key string
		// 删除失败的错误代码
		Code string
		// 删除失败的错误信息
		Message string
	} `xml:"Error,omitempty"`
}

ObjectDeleteMultiResult ...

https://cloud.tencent.com/document/product/436/8289

type ObjectGetACLResult added in v0.3.0 

type ObjectGetACLResult ACLXml

ObjectGetACLResult ...

type ObjectGetOptions added in v0.3.0 

type ObjectGetOptions struct {
	// 设置响应头部中的 Content-Type 参数
	ResponseContentType string `url:"response-content-type,omitempty" header:"-"`
	// 设置响应头部中的 Content-Language 参数
	ResponseContentLanguage string `url:"response-content-language,omitempty" header:"-"`
	// 设置响应头部中的 Content-Expires 参数
	ResponseExpires string `url:"response-expires,omitempty" header:"-"`
	// 设置响应头部中的 Cache-Control 参数
	ResponseCacheControl string `url:"response-cache-control,omitempty" header:"-"`
	// 设置响应头部中的 Content-Disposition 参数
	ResponseContentDisposition string `url:"response-content-disposition,omitempty" header:"-"`
	// 设置响应头部中的 Content-Encoding 参数
	ResponseContentEncoding string `url:"response-content-encoding,omitempty" header:"-"`
	// RFC 2616 中定义的指定文件下载范围，以字节（bytes）为单位
	Range string `url:"-" header:"Range,omitempty"`
	// 如果文件修改时间早于或等于指定时间，才返回文件内容。否则返回 412 (precondition failed)
	IfUnmodifiedSince string `url:"-" header:"If-Unmodified-Since,omitempty"`
	// 当 Object 在指定时间后被修改，则返回对应 Object meta 信息，否则返回 304(not modified)
	IfModifiedSince string `url:"-" header:"If-Modified-Since,omitempty"`
	// 当 ETag 与指定的内容一致，才返回文件。否则返回 412 (precondition failed)
	IfMatch string `url:"-" header:"If-Match,omitempty"`
	// 当 ETag 与指定的内容不一致，才返回文件。否则返回 304 (not modified)
	IfNoneMatch string `url:"-" header:"If-None-Match,omitempty"`

	// 预签名授权 URL
	PresignedURL *url.URL `header:"-" url:"-" xml:"-"`
}

ObjectGetOptions ...

https://cloud.tencent.com/document/product/436/7753

type ObjectHeadOptions added in v0.3.0 

type ObjectHeadOptions struct {
	// 当 Object 在指定时间后被修改，则返回对应 Object 的 meta 信息，否则返回 304
	IfModifiedSince string `url:"-" header:"If-Modified-Since,omitempty"`
}

ObjectHeadOptions ...

type ObjectListPartsOptions added in v0.3.0 

type ObjectListPartsOptions struct {
	// 规定返回值的编码方式
	EncodingType string `url:"Encoding-type,omitempty"`
	// 单次返回最大的条目数量，默认1000
	MaxParts int `url:"max-parts,omitempty"`
	// 默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始
	PartNumberMarker int `url:"part-number-marker,omitempty"`
}

ObjectListPartsOptions ...

type ObjectListPartsResult added in v0.3.0 

type ObjectListPartsResult struct {
	XMLName xml.Name `xml:"ListPartsResult"`
	// 分块上传的目标 Bucket，存储桶的名字，由用户自定义字符串和系统生成 appid 数字串由中划线连接而成，
	// 如：mybucket-1250000000
	Bucket string
	// 编码格式
	EncodingType string `xml:"Encoding-type,omitempty"`
	// Object 的名字
	Key string
	// 标识本次分块上传的 ID
	UploadID string `xml:"UploadId"`
	// 用来表示这些分块所有者的信息
	Initiator *Initiator `xml:"Initiator,omitempty"`
	// 用来表示这些分块所有者的信息
	Owner *Owner `xml:"Owner,omitempty"`
	// 用来表示这些分块的存储级别，枚举值：STANDARD，STANDARD_IA，ARCHIVE
	StorageClass string
	// 默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始
	PartNumberMarker int
	// 假如返回条目被截断，则返回 NextMarker 就是下一个条目的起点
	NextPartNumberMarker int `xml:"NextPartNumberMarker,omitempty"`
	// 单次返回最大的条目数量
	MaxParts int
	// 响应请求条目是否被截断，布尔值：true，false
	IsTruncated bool
	// 元数据信息
	Parts []Object `xml:"Part,omitempty"`
}

ObjectListPartsResult ...

https://cloud.tencent.com/document/product/436/7747

type ObjectOptionsOptions added in v0.3.0 

type ObjectOptionsOptions struct {
	// 模拟跨域访问的请求来源域名，必选
	Origin string `url:"-" header:"Origin"`
	// 模拟跨域访问的请求 HTTP 方法，必选
	AccessControlRequestMethod string `url:"-" header:"Access-Control-Request-Method"`
	// 模拟跨域访问的请求头部
	AccessControlRequestHeaders string `url:"-" header:"Access-Control-Request-Headers,omitempty"`
}

ObjectOptionsOptions ...

https://cloud.tencent.com/document/product/436/8288

type ObjectPutACLOptions added in v0.3.0 

type ObjectPutACLOptions struct {
	// Header 和 Body 二选一
	Header *ACLHeaderOptions `url:"-" xml:"-"`
	Body   *ACLXml           `url:"-" header:"-"`
}

ObjectPutACLOptions ...

type ObjectPutHeaderOptions added in v0.3.0 

type ObjectPutHeaderOptions struct {
	// RFC 2616 中定义的缓存策略，将作为 Object 元数据保存。
	CacheControl string `header:"Cache-Control,omitempty" url:"-"`
	// RFC 2616 中定义的文件名称，将作为 Object 元数据保存。
	ContentDisposition string `header:"Content-Disposition,omitempty" url:"-"`
	// RFC 2616 中定义的编码格式，将作为 Object 元数据保存。
	ContentEncoding string `header:"Content-Encoding,omitempty" url:"-"`
	// RFC 2616 中定义的内容类型（MIME），将作为 Object 元数据保存。
	ContentType string `header:"Content-Type,omitempty" url:"-"`
	//
	ContentLength int `header:"Content-Length,omitempty" url:"-"`
	// RFC 2616 中定义的文件日期和时间，将作为 Object 元数据保存。
	Expect          string `header:"Expect,omitempty" url:"-"`
	Expires         string `header:"Expires,omitempty" url:"-"`
	XCosContentSHA1 string `header:"x-cos-content-sha1,omitempty" url:"-"`
	// 自定义的 x-cos-meta-* header
	// 包括用户自定义头部后缀和用户自定义头部信息，将作为 Object 元数据返回，大小限制为 2KB。
	// 注意：用户自定义头部信息支持下划线，但用户自定义头部后缀不支持下划线。
	XCosMetaXXX *http.Header `header:"x-cos-meta-*,omitempty" url:"-"`
	// 设置 Object 的存储级别，枚举值：STANDARD, STANDARD_IA，默认值：STANDARD
	XCosStorageClass string `header:"x-cos-storage-class,omitempty" url:"-"`

	// XCosServerSideEncryption 用于指定腾讯云 COS 在数据存储时，应用数据加密的保护策略。
	// 腾讯云 COS 会帮助您在数据写入数据中心时自动加密，并在您取用该数据时自动解密。
	// 目前支持使用腾讯云 COS 主密钥对数据进行 AES-256 加密。
	// 如果您需要对数据启用服务端加密，则需指定 XCosServerSideEncryption。
	//
	// 指定将对象启用服务端加密的方式。使用 COS 主密钥加密填写：AES256
	XCosServerSideEncryption string `header:"x-cos-server-side-encryption,omitempty" url:"-"`
}

ObjectPutHeaderOptions ...

type ObjectPutOptions added in v0.3.0 

type ObjectPutOptions struct {
	*ACLHeaderOptions       `header:",omitempty" url:"-" xml:"-"`
	*ObjectPutHeaderOptions `header:",omitempty" url:"-" xml:"-"`

	// 预签名授权 URL
	PresignedURL *url.URL `header:"-" url:"-" xml:"-"`
}

ObjectPutOptions ...

type ObjectService added in v0.2.0 

type ObjectService service

ObjectService ...

Object 相关 API

func (*ObjectService) AbortMultipartUpload added in v0.3.0 

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

AbortMultipartUpload ...

Abort Multipart Upload 用来实现舍弃一个分块上传并删除已上传的块。当您调用 Abort Multipart Upload 时， 如果有正在使用这个Upload Parts上传块的请求，则Upload Parts会返回失败。当该UploadID不存在时，会返回404 NoSuchUpload。

建议您及时完成分块上传或者舍弃分块上传，因为已上传但是未终止的块会占用存储空间进而产生存储费用。

https://cloud.tencent.com/document/product/436/7740

func (*ObjectService) Append added in v0.3.0 

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

Append ...

Append请求可以将一个文件（Object）以分块追加的方式上传至 Bucket 中。使用Append Upload的文件必须事前被设定为Appendable。 当Appendable的文件被执行Put Object的操作以后，文件被覆盖，属性改变为Normal。

文件属性可以在Head Object操作中被查询到，当您发起Head Object请求时，会返回自定义Header『x-cos-object-type』，该Header只有两个枚举值：Normal或者Appendable。

追加上传建议文件大小1M - 5G。如果position的值和当前Object的长度不致，COS会返回409错误。 如果Append一个Normal的Object，COS会返回409 ObjectNotAppendable。

Appendable的文件不可以被复制，不参与版本管理，不参与生命周期管理，不可跨区域复制。

当 r 不是 bytes.Buffer/bytes.Reader/strings.Reader 时，必须指定 opt.ObjectPutHeaderOptions.ContentLength 当 r 是个 io.ReadCloser 时 Append 方法不会自动调用 r.Close()，用户需要自行选择合适的时机去调用 r.Close() 方法对 r 进行资源回收

https://www.qcloud.com/document/product/436/7741

func (*ObjectService) CompleteMultipartUpload added in v0.3.0 

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

CompleteMultipartUpload ...

Complete Multipart Upload用来实现完成整个分块上传。当您已经使用Upload Parts上传所有块以后，你可以用该API完成上传。 在使用该API时，您必须在Body中给出每一个块的PartNumber和ETag，用来校验块的准确性。

由于分块上传的合并需要数分钟时间，因而当合并分块开始的时候，COS就立即返回200的状态码，在合并的过程中， COS会周期性的返回空格信息来保持连接活跃，直到合并完成，COS会在Body中返回合并后块的内容。

当上传块小于1 MB的时候，在调用该请求时，会返回400 EntityTooSmall； 当上传块编号不连续的时候，在调用该请求时，会返回400 InvalidPart； 当请求Body中的块信息没有按序号从小到大排列的时候，在调用该请求时，会返回400 InvalidPartOrder； 当UploadId不存在的时候，在调用该请求时，会返回404 NoSuchUpload。

建议您及时完成分块上传或者舍弃分块上传，因为已上传但是未终止的块会占用存储空间进而产生存储费用。

https://cloud.tencent.com/document/product/436/7742

func (*ObjectService) Copy added in v0.7.0 

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

Copy ...

Put Object Copy 请求实现将一个文件从源路径复制到目标路径。建议文件大小 1M 到 5G， 超过 5G 的文件请使用分块上传 Upload - Copy。在拷贝的过程中，文件元属性和 ACL 可以被修改。

用户可以通过该接口实现文件移动，文件重命名，修改文件属性和创建副本。

版本

  • 默认情况下，在目标存储桶上启用版本控制，对象存储会为正在复制的对象生成唯一的版本 ID。此版本 ID 与源对象的版本 ID 不同。 对象存储会在 x-cos-version-id 响应中的响应标头中返回复制对象的版本 ID。
  • 如果您在目标存储桶没有启用版本控制或暂停版本控制，则对象存储生成的版本 ID 始终为 null。

注意：在跨帐号复制的时候，需要先设置被复制文件的权限为公有读，或者对目标帐号赋权，同帐号则不需要。

https://cloud.tencent.com/document/product/436/10881

func (*ObjectService) Delete added in v0.3.0 

func (s *ObjectService) Delete(ctx context.Context, name string) (*Response, error)

Delete Object 接口请求可以在 COS 的 Bucket 中将一个文件（Object）删除。该操作需要请求者对 Bucket 有 WRITE 权限。

细节分析

* 在 DELETE Object 请求中删除一个不存在的 Object，仍然认为是成功的，返回 204 No Content。 * DELETE Object 要求用户对该 Object 要有写权限。

https://cloud.tencent.com/document/product/436/7743

func (*ObjectService) DeleteMulti added in v0.3.0 

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

DeleteMulti ...

Delete Multiple Object请求实现批量删除文件，最大支持单次删除1000个文件。 对于返回结果，COS提供Verbose和Quiet两种结果模式。Verbose模式将返回每个Object的删除结果； Quiet模式只返回报错的Object信息。

细节分析

  • 每一个批量删除请求，最多只能包含 1000个 需要删除的对象；
  • 批量删除支持二种模式的放回，verbose 模式和 quiet 模式，默认为 verbose 模式。 verbose 模式返回每个 key 的删除情况，quiet 模式只返回删除失败的 key 的情况；
  • 批量删除需要携带 Content-MD5 头部，用以校验请求 body 没有被修改；
  • 批量删除请求允许删除一个不存在的 key，仍然认为成功。

https://cloud.tencent.com/document/product/436/8289

func (*ObjectService) Get added in v0.3.0 

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

Get Object 请接口请求可以在 COS 的存储桶中将一个文件（对象）下载至本地。 该操作需要请求者对目标对象具有读权限或目标对象对所有人都开放了读权限（公有读）。

版本

当启用多版本，该 GET 操作返回对象的当前版本。要返回不同的版本，请使用 versionId 参数。

注意

如果该对象的当前版本是删除标记，则 COS 的行为表现为该对象不存在，并返回响应 x-cos-delete-marker: true。

https://cloud.tencent.com/document/product/436/7753

func (*ObjectService) GetACL added in v0.3.0 

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

GetACL Get Object ACL接口实现使用API读取Object的ACL表，只有所有者有权操作。

默认情况下，该 GET 操作返回对象的当前版本。您如果需要返回不同的版本，请使用 version Id 子资源。

https://cloud.tencent.com/document/product/436/7744

func (*ObjectService) Head added in v0.3.0 

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

Head Object请求可以取回对应Object的元数据，Head的权限与Get的权限一致

默认情况下，HEAD 操作从当前版本的对象中检索元数据。如要从不同版本检索元数据，请使用 versionId 子资源。

https://cloud.tencent.com/document/product/436/7745

func (*ObjectService) InitiateMultipartUpload added in v0.3.0 

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

InitiateMultipartUpload ...

Initiate Multipart Upload请求实现初始化分片上传，成功执行此请求以后会返回Upload ID用于后续的Upload Part请求。

https://cloud.tencent.com/document/product/436/7746

func (*ObjectService) ListParts added in v0.3.0 

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

ListParts ...

List Parts 用来查询特定分块上传中的已上传的块，即罗列出指定 UploadId 所属的所有已上传成功的分块。

https://cloud.tencent.com/document/product/436/7747

func (*ObjectService) ListPartsWithOpt added in v0.13.0 

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

ListPartsWithOpt ...

ListParts 方法的补充，解决 ListParts 不支持指定参数的问题。 List Parts 用来查询特定分块上传中的已上传的块，即罗列出指定 UploadId 所属的所有已上传成功的分块。

https://cloud.tencent.com/document/product/436/7747

func (*ObjectService) Options added in v0.3.0 

func (s *ObjectService) Options(ctx context.Context, name string, opt *ObjectOptionsOptions) (*Response, error)

Options Object 接口实现 Object 跨域访问配置的预请求。 即在发送跨域请求之前会发送一个 OPTIONS 请求并带上特定的来源域，HTTP 方法和 Header 信息等给 COS， 以决定是否可以发送真正的跨域请求。当 CORS 配置不存在时，请求返回 403 Forbidden。 可以通过 PUT Bucket cors 接口来开启 Bucket 的 CORS 支持。

https://cloud.tencent.com/document/product/436/8288

func (*ObjectService) PresignedURL added in v0.9.0 

func (s *ObjectService) PresignedURL(ctx context.Context, httpMethod, name string, auth Auth, opt interface{}) (*url.URL, error)

PresignedURL 生成预签名授权 URL，可用于无需知道 SecretID 和 SecretKey 就可以上传和下载文件 。

httpMethod:

  • 下载文件：http.MethodGet
  • 上传文件: http.MethodPut

下载文件 时 opt 可以是 *ObjectGetOptions ，上传文件时 opt 可以是 *ObjectPutOptions

https://cloud.tencent.com/document/product/436/14116 https://cloud.tencent.com/document/product/436/14114

func (*ObjectService) Put added in v0.3.0 

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

Put Object请求可以将一个文件（Object）上传至指定Bucket。

版本

  • 如果对存储桶启用版本控制，对象存储将自动为要添加的对象生成唯一的版本 ID。 对象存储使用 x-cos-version-id 响应头部在响应中返回此标识。
  • 如果需要暂停存储桶的版本控制，则对象存储始终将其 null 用作存储在存储桶中的对象的版本 ID。

细节分析

  • 需要有 Bucket 的写权限；
  • 如果请求头的 Content-Length 值小于实际请求体（body）中传输的数据长度，COS 仍将成功创建文件， 但 Object 大小只等于 Content-Length 中定义的大小，其他数据将被丢弃；
  • 如果试图添加的 Object 的同名文件已经存在，那么新上传的文件，将覆盖原来的文件，成功时返回 200 OK。

当 r 是个 io.ReadCloser 时 Put 方法不会自动调用 r.Close()，用户需要自行选择合适的时机去调用 r.Close() 方法对 r 进行资源回收

https://cloud.tencent.com/document/product/436/7749

func (*ObjectService) PutACL added in v0.3.0 

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

PutACL 使用API写入Object的ACL表。

https://cloud.tencent.com/document/product/436/7748

func (*ObjectService) UploadPart added in v0.3.0 

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

UploadPart ...

Upload Part 接口请求实现将对象按照分块的方式上传到 COS。 最多支持 10000 分块，每个分块大小为 1 MB 到 5 GB ，最后一个分块可以小于 1 MB。

细节分析

* 分块上传首先需要进行初始化，使用 Initiate Multipart Upload 接口实现，初始化后会得到一个 uploadId ，唯一标识本次上传； * 在每次请求 Upload Part 时，需要携带 partNumber 和 uploadId，partNumber 为块的编号，支持乱序上传； * 当传入 uploadId 和 partNumber 都相同的时候，后传入的块将覆盖之前传入的块。当 uploadId 不存在时会返回 404 错误，NoSuchUpload。

当 r 是个 io.ReadCloser 时 UploadPart 方法不会自动调用 r.Close()，用户需要自行选择合适的时机去调用 r.Close() 方法对 r 进行资源回收

https://cloud.tencent.com/document/product/436/7750

type ObjectUploadPartOptions added in v0.3.0 

type ObjectUploadPartOptions struct {
	// RFC 2616 中定义的 HTTP 请求内容长度（字节）
	Expect          string `header:"Expect,omitempty" url:"-"`
	XCosContentSHA1 string `header:"x-cos-content-sha1" url:"-"`
	// RFC 1864 中定义的经过Base64编码的128-bit 内容 MD5 校验值。此头部用来校验文件内容是否发生变化
	ContentMD5 string `header:"Content-MD5" url:"-"`
	// RFC 2616 中定义的 HTTP 请求内容长度（字节）
	ContentLength int `header:"Content-Length,omitempty" url:"-"`
}

ObjectUploadPartOptions ...

type Owner 

type Owner struct {
	UIN         string `xml:"uin,omitempty"`
	ID          string `xml:",omitempty"`
	DisplayName string `xml:",omitempty"`
}

Owner ...

type Response added in v0.3.0 

type Response struct {
	*http.Response
}

Response API 响应

func (*Response) MetaHeaders added in v0.11.0 

func (resp *Response) MetaHeaders() http.Header

MetaHeaders 用户自定义的元数据

func (*Response) ObjectType added in v0.11.0 

func (resp *Response) ObjectType() string

ObjectType 用来表示 Object 是否可以被追加上传，枚举值：normal 或者 appendable

func (*Response) RequestID added in v0.11.0 

func (resp *Response) RequestID() string

RequestID 每次请求发送时，服务端将会自动为请求生成一个ID。

func (*Response) ServerSideEncryption added in v0.11.0 

func (resp *Response) ServerSideEncryption() string

ServerSideEncryption 如果通过 COS 管理的服务端加密来存储对象，响应将包含此头部和所使用的加密算法的值，AES256。

func (*Response) StorageClass added in v0.11.0 

func (resp *Response) StorageClass() string

StorageClass Object 的存储级别，枚举值：STANDARD，STANDARD_IA

func (*Response) TraceID added in v0.11.0 

func (resp *Response) TraceID() string

TraceID 每次请求出错时，服务端将会自动为这个错误生成一个ID。

func (*Response) VersionID added in v0.11.0 

func (resp *Response) VersionID() string

VersionID 如果检索到的对象具有唯一的版本ID，则返回版本ID。

type ResponseParser added in v0.12.0 

type ResponseParser interface {
	// caller 中包含了从哪个方法触发的 http 请求的信息
	// result: 反序列化后的结果将存储在指针类型的 result 中
	ParseResponse(ctx context.Context, caller Caller, resp *http.Response, result interface{}) (*Response, error)
}

ResponseParser 定义了一个用于解析响应的接口（反序列化 body 或错误检查）。 可以用于替换默认的解析响应的实现， 从而实现使用自定义的解析方法或写单元测试时 mock 接口结果的需求

实现自定义的 ResponseParser 时可以参考 DefaultResponseParser 的实现。

type Sender added in v0.12.0 

type Sender interface {
	// caller 中包含了从哪个方法触发的 http 请求的信息
	// 当 error != nil 时将不会调用 ResponseParser.ParseResponse 解析响应
	Send(ctx context.Context, caller Caller, req *http.Request) (*http.Response, error)
}

Sender 定义了一个用来发送 http 请求的接口。 可以用于替换默认的基于 http.Client 的实现， 从而实现使用第三方 http client 或写单元测试时 mock 接口结果的需求。

实现自定义的 Sender 时可以参考 DefaultSender 的实现。

type ServiceGetResult added in v0.3.0 

type ServiceGetResult struct {
	XMLName xml.Name `xml:"ListAllMyBucketsResult"`
	Owner   *Owner   `xml:"Owner"`
	Buckets []Bucket `xml:"Buckets>Bucket,omitempty"`
}

ServiceGetResult ...

type ServiceService 

type ServiceService service

ServiceService ...

Service 相关 API

func (*ServiceService) Get 

func (s *ServiceService) Get(ctx context.Context) (*ServiceGetResult, *Response, error)

Get Service 接口是用来获取请求者名下的所有存储空间列表（Bucket list）。

https://cloud.tencent.com/document/product/436/8291

Source Files

View all Source files

Directories

Path Synopsis
_example
bucket
object
service

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.