kodocli

Documentation

Overview

包 qiniupkg.com/api.v7/kodocli 提供了在客户端调用七牛云存储部分服务的能力

客户端，严谨说是非可信环境，主要是指在用户端执行的环境，比如：Android/iOS 设备、Windows/Mac/Linux 桌面环境、也包括浏览器（如果浏览器能够执行 Go 语言代码的话）。

注意，在这种场合下您不应该在任何地方配置 AccessKey/SecretKey。泄露 AccessKey/SecretKey 如同泄露您的用户名/密码一样十分危险，会影响您的数据安全。

第一个问题是如何上传文件。因为是在非可信环境，所以我们首先是要授予它有上传文件的能力。答案是给它颁发上传凭证。假设服务端也是 Go 语言，那么：

import "qiniupkg.com/api.v7/kodo"

kodo.SetMac("your-access-key", "your-secret-key") // 配置 AccessKey/SecretKey

zone := 0
c := kodo.New(zone, nil) // 创建一个 Client 对象

bucket := "your-bucket-name"
key := "foo/bar.jpg"
policy := &kodo.PutPolicy{
	Scope: bucket + ":" + key, // 上传文件的限制条件，这里限制只能上传一个名为 "foo/bar.jpg" 的文件
	Expires: 3600, // 这是限制上传凭证(uptoken)的过期时长，3600 是一小时
	...
}
uptoken := c.MakeUptoken(policy) // 生成上传凭证

生成上传凭证之后，通过某种方式将 uptoken 发送到客户端。这样客户端就可以上传文件了：

zone := 0
uploader := kodocli.NewUploader(zone, nil)
ctx := context.Background()

key := "foo/bar.jpg"
localFile := "/your/local/image/file.jpg"
err := uploader.PutFile(ctx, nil, uptoken, key, localFile, nil)
if err != nil {
	... // 上传文件失败处理
	return
}

注意，如果客户端上传的 key 不是 uptoken 所要求的 "foo/bar.jpg"，那么上传就会被拒绝。

如果我们希望一个 uptoken 可以上传多个文件，那么服务端颁发 uptoken 的代码需要调整下：

bucket := "your-bucket-name"
policy := &kodo.PutPolicy{
	Scope: bucket, // 上传文件的限制条件，这里是只限制了要上传到 "your-bucket-name" 空间
	Expires: 3600, // 这是限制上传凭证(uptoken)的过期时长，3600 是一小时
	...
}
uptoken := c.MakeUptoken(policy)

颁发这样的 uptoken 给客户端，客户端就可以用它上传任意名字(key)的文件，前提是服务器上还没有同名的文件。

特别需要注意的是，这种情况下服务端会拒绝已经有同名文件的上传请求，而不是覆盖服务器上已有的文件。这是出于数据安全的考虑。我们并不非常推荐 uptoken 复用的做法，除了注意文件名可能冲突外，还需要注意 uptoken 是有时效的，过期就需要重新向服务器申请新的上传凭证。

搞定文件的上传后，第二个问题是如何下载文件。如果是公开文件，我们只需要：

import "net/http"

domain := "domain-of-your-bucket.com" // 您的空间绑定的域名，这个可以在七牛的Portal中查到
baseUrl := kodocli.MakeBaseUrl(domain, "foo/bar.jpg") // 得到下载 url
resp, err := http.Get(baseUrl)
...

但是对于私有空间，事情要复杂一些，需要客户端向您的业务服务器申请下载该文件。业务服务器确认该用户有权访问，则返回一个临时有效的 privateUrl。具体如何生成 privateUrl，可以看服务端 SDK 相关的文档介绍。

Index

• Constants
• Variables
• func BlockCount(fsize int64) int
• func MakeBaseUrl(domain, key string) (baseUrl string)
• func NewUptokenClient(token string, transport http.RoundTripper) *http.Client
• func SetAppName(userApp string) error
• func SetSettings(v *Settings)
• type BlkputRet
• type Policy
• type PutExtra
• type PutRet
• type RputExtra
• type Settings
• type UploadConfig
• type Uploader
  • func NewUploader(zone int, cfg *UploadConfig) (p Uploader)
  • func NewUploaderWithoutZone(cfg *UploadConfig) (p Uploader)
  • func (p Uploader) Mkfile(ctx Context, uphosts []string, ret interface{}, key string, hasKey bool, ...) (err error)
  • func (p Uploader) Put(ctx Context, ret interface{}, uptoken, key string, data io.Reader, size int64, ...) error
  • func (p Uploader) PutFile(ctx Context, ret interface{}, uptoken, key, localFile string, extra *PutExtra) (err error)
  • func (p Uploader) PutFileWithoutKey(ctx Context, ret interface{}, uptoken, localFile string, extra *PutExtra) (err error)
  • func (p Uploader) PutWithoutKey(ctx Context, ret interface{}, uptoken string, data io.Reader, size int64, ...) error
  • func (p Uploader) ResumableBput(ctx Context, uphosts []string, ret *BlkputRet, f io.ReaderAt, ...) (err error)
  • func (p Uploader) Rput(ctx Context, ret interface{}, uptoken string, key string, f io.ReaderAt, ...) error
  • func (p Uploader) RputFile(ctx Context, ret interface{}, uptoken, key, localFile string, extra *RputExtra) (err error)
  • func (p Uploader) RputFileWithoutKey(ctx Context, ret interface{}, uptoken, localFile string, extra *RputExtra) (err error)
  • func (p Uploader) RputWithoutKey(ctx Context, ret interface{}, uptoken string, f io.ReaderAt, fsize int64, ...) error

Constants

const (
	DontCheckCrc    = 0
	CalcAndCheckCrc = 1
	CheckCrc        = 2
)

const (
	InvalidCtx = 701 // UP: 无效的上下文(bput)，可能情况：Ctx非法或者已经被淘汰（太久未使用）
)

Variables

var (
	ErrInvalidPutProgress = errors.New("invalid put progress")
	ErrPutFailed          = errors.New("resumable put failed")
	ErrUnmatchedChecksum  = errors.New("unmatched checksum")
	ErrBadToken           = errors.New("invalid token")
)

Functions

func BlockCount

func BlockCount(fsize int64) int

func MakeBaseUrl

func MakeBaseUrl(domain, key string) (baseUrl string)

根据空间(Bucket)的域名，以及文件的 key，获得 baseUrl。 如果空间是 public 的，那么通过 baseUrl 可以直接下载文件内容。 如果空间是 private 的，那么需要对 baseUrl 进行私有签名得到一个临时有效的 privateUrl 进行下载。

func NewUptokenClient

func NewUptokenClient(token string, transport http.RoundTripper) *http.Client

func SetAppName

func SetAppName(userApp string) error

设置使用这个SDK的应用程序名。userApp 必须满足 [A-Za-z0-9_\ \-\.]*

func SetSettings

func SetSettings(v *Settings)

Types

type BlkputRet

type BlkputRet struct {
	Ctx      string `json:"ctx"`
	Checksum string `json:"checksum"`
	Crc32    uint32 `json:"crc32"`
	Offset   uint32 `json:"offset"`
	Host     string `json:"host"`
}

type Policy

type Policy struct {
	Scope string `json:"scope"`
}

type PutExtra

type PutExtra struct {
	// 可选，用户自定义参数，必须以 "x:" 开头。若不以x:开头，则忽略。
	Params map[string]string

	// 可选，当为 "" 时候，服务端自动判断。
	MimeType string

	Crc32 uint32

	// CheckCrc == 0 (DontCheckCrc): 表示不进行 crc32 校验
	// CheckCrc == 1 (CalcAndCheckCrc): 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值
	// CheckCrc == 2 (CheckCrc): 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量
	CheckCrc uint32

	// 上传事件：进度通知。这个事件的回调函数应该尽可能快地结束。
	OnProgress func(fsize, uploaded int64)
}

上传的额外可选项

type PutRet

type PutRet struct {
	Hash         string `json:"hash"`
	PersistentId string `json:"persistentId"`
	Key          string `json:"key"`
}

如果 uptoken 没有指定 ReturnBody，那么返回值是标准的 PutRet 结构

type RputExtra

type RputExtra struct {
	Params     map[string]string                             // 可选。用户自定义参数，以"x:"开头 否则忽略
	MimeType   string                                        // 可选。
	ChunkSize  int                                           // 可选。每次上传的Chunk大小
	TryTimes   int                                           // 可选。尝试次数
	Progresses []BlkputRet                                   // 可选。上传进度
	Notify     func(blkIdx int, blkSize int, ret *BlkputRet) // 可选。进度提示（注意多个block是并行传输的）
	NotifyErr  func(blkIdx int, blkSize int, err error)
}

type Settings

type Settings struct {
	TaskQsize int // 可选。任务队列大小。为 0 表示取 Workers * 4。
	Workers   int // 并行 Goroutine 数目。
	ChunkSize int // 默认的Chunk大小，不设定则为256k
	TryTimes  int // 默认的尝试次数，不设定则为3
}

type UploadConfig

type UploadConfig struct {
	UpHosts   []string
	Transport http.RoundTripper

	APIHost string
	Scheme  string
}

type Uploader

type Uploader struct {
	Conn    rpc.Client
	UpHosts []string
}

func NewUploader

func NewUploader(zone int, cfg *UploadConfig) (p Uploader)

func NewUploaderWithoutZone

func NewUploaderWithoutZone(cfg *UploadConfig) (p Uploader)

func (Uploader) Mkfile

func (p Uploader) Mkfile(
	ctx Context, uphosts []string, ret interface{}, key string, hasKey bool, fsize int64, extra *RputExtra) (err error)

func (Uploader) Put

func (p Uploader) Put(
	ctx Context, ret interface{}, uptoken, key string, data io.Reader, size int64, extra *PutExtra) error

上传一个文件。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 key 是要上传的文件访问路径。比如："foo/bar.jpg"。注意我们建议 key 不要以 '/' 开头。另外，key 为空字符串是合法的。 data 是文件内容的访问接口（io.Reader）。 fsize 是要上传的文件大小。 extra 是上传的一些可选项。详细见 PutExtra 结构的描述。

func (Uploader) PutFile

func (p Uploader) PutFile(
	ctx Context, ret interface{}, uptoken, key, localFile string, extra *PutExtra) (err error)

上传一个文件。 和 Put 不同的只是一个通过提供文件路径来访问文件内容，一个通过 io.Reader 来访问。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 key 是要上传的文件访问路径。比如："foo/bar.jpg"。注意我们建议 key 不要以 '/' 开头。另外，key 为空字符串是合法的。 localFile 是要上传的文件的本地路径。 extra 是上传的一些可选项。详细见 PutExtra 结构的描述。

func (Uploader) PutFileWithoutKey

func (p Uploader) PutFileWithoutKey(
	ctx Context, ret interface{}, uptoken, localFile string, extra *PutExtra) (err error)

上传一个文件。文件的访问路径（key）自动生成。 如果 uptoken 中设置了 SaveKey，那么按 SaveKey 要求的规则生成 key，否则自动以文件的 hash 做 key。 和 RputWithoutKey 不同的只是一个通过提供文件路径来访问文件内容，一个通过 io.Reader 来访问。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 localFile 是要上传的文件的本地路径。 extra 是上传的一些可选项。详细见 PutExtra 结构的描述。

func (Uploader) PutWithoutKey

func (p Uploader) PutWithoutKey(
	ctx Context, ret interface{}, uptoken string, data io.Reader, size int64, extra *PutExtra) error

上传一个文件。文件的访问路径（key）自动生成。 如果 uptoken 中设置了 SaveKey，那么按 SaveKey 要求的规则生成 key，否则自动以文件的 hash 做 key。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 data 是文件内容的访问接口（io.Reader）。 fsize 是要上传的文件大小。 extra 是上传的一些可选项。详细见 PutExtra 结构的描述。

func (Uploader) ResumableBput

func (p Uploader) ResumableBput(
	ctx Context, uphosts []string, ret *BlkputRet, f io.ReaderAt, blkIdx, blkSize int, extra *RputExtra) (err error)

func (Uploader) Rput

func (p Uploader) Rput(
	ctx Context, ret interface{}, uptoken string,
	key string, f io.ReaderAt, fsize int64, extra *RputExtra) error

上传一个文件，支持断点续传和分块上传。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 key 是要上传的文件访问路径。比如："foo/bar.jpg"。注意我们建议 key 不要以 '/' 开头。另外，key 为空字符串是合法的。 f 是文件内容的访问接口。考虑到需要支持分块上传和断点续传，要的是 io.ReaderAt 接口，而不是 io.Reader。 fsize 是要上传的文件大小。 extra 是上传的一些可选项。详细见 RputExtra 结构的描述。

func (Uploader) RputFile

func (p Uploader) RputFile(
	ctx Context, ret interface{}, uptoken, key, localFile string, extra *RputExtra) (err error)

上传一个文件，支持断点续传和分块上传。 和 Rput 不同的只是一个通过提供文件路径来访问文件内容，一个通过 io.ReaderAt 来访问。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 key 是要上传的文件访问路径。比如："foo/bar.jpg"。注意我们建议 key 不要以 '/' 开头。另外，key 为空字符串是合法的。 localFile 是要上传的文件的本地路径。 extra 是上传的一些可选项。详细见 RputExtra 结构的描述。

func (Uploader) RputFileWithoutKey

func (p Uploader) RputFileWithoutKey(
	ctx Context, ret interface{}, uptoken, localFile string, extra *RputExtra) (err error)

上传一个文件，支持断点续传和分块上传。文件的访问路径（key）自动生成。 如果 uptoken 中设置了 SaveKey，那么按 SaveKey 要求的规则生成 key，否则自动以文件的 hash 做 key。 和 RputWithoutKey 不同的只是一个通过提供文件路径来访问文件内容，一个通过 io.ReaderAt 来访问。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 localFile 是要上传的文件的本地路径。 extra 是上传的一些可选项。详细见 RputExtra 结构的描述。

func (Uploader) RputWithoutKey

func (p Uploader) RputWithoutKey(
	ctx Context, ret interface{}, uptoken string, f io.ReaderAt, fsize int64, extra *RputExtra) error

上传一个文件，支持断点续传和分块上传。文件的访问路径（key）自动生成。 如果 uptoken 中设置了 SaveKey，那么按 SaveKey 要求的规则生成 key，否则自动以文件的 hash 做 key。

ctx 是请求的上下文。 ret 是上传成功后返回的数据。如果 uptoken 中没有设置 CallbackUrl 或 ReturnBody，那么返回的数据结构是 PutRet 结构。 uptoken 是由业务服务器颁发的上传凭证。 f 是文件内容的访问接口。考虑到需要支持分块上传和断点续传，要的是 io.ReaderAt 接口，而不是 io.Reader。 fsize 是要上传的文件大小。 extra 是上传的一些可选项。详细见 RputExtra 结构的描述。