kodo

package
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: Jan 12, 2024 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultRsHost  = "rs.qiniu.com"
	DefaultRsfHost = "rsf.qiniu.com"
	DefaultAPIHost = "api.qiniu.com"
	DefaultPubHost = "pu.qbox.me:10200"
)

资源管理相关的默认域名

View Source 
const (
	// 获取下一个分片Reader失败
	ErrNextReader = "ErrNextReader"
	// 超过了最大的重试上传次数
	ErrMaxUpRetry = "ErrMaxUpRetry"
)

Variables

View Source 
var UcHost = ""

UcHost 为查询空间相关域名的 API 服务地址 设置 UcHost 时，如果不指定 scheme 默认会使用 https Deprecated 使用 SetUcHosts 替换

Functions

func EncodedEntry 

func EncodedEntry(bucket, key string) string

EncodedEntry 生成URL Safe Base64编码的 Entry

Types

type BucketManager 

type BucketManager struct {
	Client *clientv1.Client
	Mac    *auth.Credentials
	Cfg    *Config
}

BucketManager 提供了对资源进行管理的操作

func NewBucketManager 

func NewBucketManager(mac *auth.Credentials, cfg *Config) *BucketManager

NewBucketManager 用来构建一个新的资源管理对象

func (*BucketManager) Fetch 

func (m *BucketManager) Fetch(resURL, bucket, key string) (fetchRet FetchRet, err error)

Fetch 根据提供的远程资源链接来抓取一个文件到空间并已指定文件名保存

func (*BucketManager) IoReqHost 

func (m *BucketManager) IoReqHost(bucket string) (reqHost string, err error)

func (*BucketManager) IovipHost 

func (m *BucketManager) IovipHost(bucket string) (iovipHost string, err error)

func (*BucketManager) ListBucket 

func (m *BucketManager) ListBucket(bucket, prefix, delimiter, marker string) (retCh chan listFilesRet2, err error)

ListBucket 用来获取空间文件列表，可以根据需要指定文件的前缀 prefix，文件的目录 delimiter，流式返回每条数据。 Deprecated

func (*BucketManager) ListBucketContext 

func (m *BucketManager) ListBucketContext(ctx context.Context, bucket, prefix, delimiter, marker string) (retCh chan listFilesRet2, err error)

ListBucketContext 用来获取空间文件列表，可以根据需要指定文件的前缀 prefix，文件的目录 delimiter，流式返回每条数据。 接受的context可以用来取消列举操作 Deprecated

func (*BucketManager) ListFiles 

func (m *BucketManager) ListFiles(bucket, prefix, delimiter, marker string,
	limit int) (entries []ListItem, commonPrefixes []string, nextMarker string, hasNext bool, err error)

ListFiles 用来获取空间文件列表，可以根据需要指定文件的前缀 prefix，文件的目录 delimiter，循环列举的时候下次 列举的位置 marker，以及每次返回的文件的最大数量limit，其中limit最大为1000。

func (*BucketManager) ListFilesWithContext 

func (m *BucketManager) ListFilesWithContext(ctx context.Context, bucket string, options ...ListInputOption) (ret *ListFilesRet, hasNext bool, err error)

ListFilesWithContext 

 @Description: 用来获取空间文件列表，可以根据需要指定文件的列举条件
 @receiver m BucketManager
 @param ctx context
 @param bucket 列举的 bucket
 @param options 列举的可选条件
				列举条件-需要列举 Key 的前缀：ListInputOptionsPrefix(prefix)
				列举条件-文件的目录分隔符：ListInputOptionsDelimiter(delimiter)
				列举条件-下次列举的位置：ListInputOptionsMarker(marker)
				列举条件-每次返回的文件的最大数量：ListInputOptionsLimit(limit) 范围：1~1000
 @return ret 列举的对象数据
 @return hasNext 是否还有数据未被列举
 @return err 列举时的错误信息

func (*BucketManager) RsfHost 

func (m *BucketManager) RsfHost(bucket string) (rsfHost string, err error)

func (*BucketManager) RsfReqHost 

func (m *BucketManager) RsfReqHost(bucket string) (reqHost string, err error)

func (*BucketManager) Zone 

func (m *BucketManager) Zone(bucket string) (z *Zone, err error)

type BucketManagerOptions 

type BucketManagerOptions struct {
	RetryMax int // 单域名重试次数，当前只有 uc 相关的服务有多域名
	// 主备域名冻结时间（默认：600s），当一个域名请求失败（单个域名会被重试 TryTimes 次），会被冻结一段时间，使用备用域名进行重试，在冻结时间内，域名不能被使用，当一个操作中所有域名竣备冻结操作不在进行重试，返回最后一次操作的错误。
	HostFreezeDuration time.Duration
}

type Config 

type Config struct {
	//兼容保留
	Zone *Region //空间所在的存储区域

	Region *Region

	// 如果设置的Host本身是以http://开头的，又设置了该字段为true，那么优先使用该字段，使用https协议
	// 同理如果该字段为false, 但是设置的host以https开头，那么使用http协议通信
	UseHTTPS      bool   //是否使用https域名
	UseCdnDomains bool   //是否使用cdn加速域名
	CentralRsHost string //中心机房的RsHost，用于list bucket

	// 兼容保留
	RsHost  string
	RsfHost string
	UpHost  string
	ApiHost string
	IoHost  string
}

func (*Config) GetRegion 

func (c *Config) GetRegion() *Region

GetRegion返回一个Region指针 默认返回最新的Region， 如果该字段没有，那么返回兼容保留的Zone, 如果都为nil, 就返回nil

type FetchRet 

type FetchRet struct {
	Hash     string `json:"hash"`
	Fsize    int64  `json:"fsize"`
	MimeType string `json:"mimeType"`
	Key      string `json:"key"`
}

FetchRet 资源抓取的返回值

type FormUploader 

type FormUploader struct {
	Client *client.Client
	Cfg    *Config
}

func NewFormUploader 

func NewFormUploader(cfg *Config) *FormUploader

func NewFormUploaderEx 

func NewFormUploaderEx(cfg *Config, clt *client.Client) *FormUploader

func (*FormUploader) Put 

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

Put 用来以表单方式上传一个文件。

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

func (*FormUploader) PutFile 

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

type ListFilesRet 

type ListFilesRet struct {
	Marker         string     `json:"marker"`
	Items          []ListItem `json:"items"`
	CommonPrefixes []string   `json:"commonPrefixes"`
}

type ListInputOption 

type ListInputOption func(options *listInputOptions)

func ListInputOptionsDelimiter 

func ListInputOptionsDelimiter(delimiter string) ListInputOption

func ListInputOptionsLimit 

func ListInputOptionsLimit(limit int) ListInputOption

func ListInputOptionsMarker 

func ListInputOptionsMarker(marker string) ListInputOption

func ListInputOptionsPrefix 

func ListInputOptionsPrefix(prefix string) ListInputOption

type ListItem 

type ListItem struct {

	// 资源名
	Key string `json:"key"`

	// 上传时间，单位：100纳秒，其值去掉低七位即为Unix时间戳。
	PutTime int64 `json:"putTime"`

	// 文件的HASH值，使用hash值算法计算。
	Hash string `json:"hash"`

	// 资源内容的大小，单位：字节。
	Fsize int64 `json:"fsize"`

	// 资源的 MIME 类型。
	MimeType string `json:"mimeType"`

	/**
	 * 文件上传时设置的endUser
	 */
	EndUser string `json:"endUser"`

	/**
	 * 资源的存储类型
	 * 0 表示标准存储
	 * 1 表示低频存储
	 * 2 表示归档存储
	 * 3 表示深度归档存储
	 */
	Type int `json:"type"`

	/**
	 * 文件的存储状态，即禁用状态和启用状态间的的互相转换，请参考：文件状态。
	 * 0 表示启用
	 * 1 表示禁用
	 */
	Status int `json:"status"`

	/**
	 * 文件的 md5 值
	 */
	Md5 string `json:"md5"`
}

ListItem 为文件列举的返回值

func (*ListItem) IsEmpty 

func (l *ListItem) IsEmpty() (empty bool)

接口可能返回空的记录

func (*ListItem) String 

func (l *ListItem) String() string

type PutExtra 

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

	UpHost string

	TryTimes int // 可选。尝试次数

	// 主备域名冻结时间（默认：600s），当一个域名请求失败（单个域名会被重试 TryTimes 次），会被冻结一段时间，使用备用域名进行重试，在冻结时间内，域名不能被使用，当一个操作中所有域名竣备冻结操作不在进行重试，返回最后一次操作的错误。
	HostFreezeDuration time.Duration

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

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

type PutPolicy 

type PutPolicy struct {

	// 指定上传的目标资源空间 Bucket 和资源键 Key（最大为 750 字节）。有三种格式：
	// <bucket>，表示允许用户上传文件到指定的 bucket。在这种格式下文件只能新增（分片上传 v1 版 需要指定 insertOnly 为 1 才是新增，否则也为覆盖上传），若已存在同名资源（且文件内容/etag不一致），上传会失败；若已存在资源的内容/etag一致，则上传会返回成功。
	// <bucket>:<key>，表示只允许用户上传指定 key 的文件。在这种格式下文件默认允许修改，若已存在同名资源则会被覆盖。如果只希望上传指定 key 的文件，并且不允许修改，那么可以将下面的 insertOnly 属性值设为 1。
	// <bucket>:<keyPrefix>，表示只允许用户上传指定以 keyPrefix 为前缀的文件，当且仅当 isPrefixalScope 字段为 1 时生效，isPrefixalScope 为 1 时无法覆盖上传。
	Scope string `json:"scope"`

	// 若为 1，表示允许用户上传以 scope 的 keyPrefix 为前缀的文件。
	IsPrefixalScope int `json:"isPrefixalScope,omitempty"`

	// 上传凭证有效截止时间。Unix时间戳，单位为秒。该截止时间为上传完成后，在七牛空间生成文件的校验时间，而非上传的开始时间，
	// 一般建议设置为上传开始时间 + 3600s，用户可根据具体的业务场景对凭证截止时间进行调整。
	Expires uint64 `json:"deadline"`

	// 若非0, 即使Scope为 Bucket:Key 的形式也是insert only
	InsertOnly uint16 `json:"insertOnly,omitempty"`

	// 唯一属主标识。特殊场景下非常有用，例如根据 App-Client 标识给图片或视频打水印。
	EndUser string `json:"endUser,omitempty"`

	// Web 端文件上传成功后，浏览器执行 303 跳转的 URL。通常用于表单上传。
	// 文件上传成功后会跳转到 <returnUrl>?upload_ret=<queryString>，<queryString>包含 returnBody 内容。
	// 如不设置 returnUrl，则直接将 returnBody 的内容返回给客户端。
	ReturnURL string `json:"returnUrl,omitempty"`

	// 上传成功后，自定义七牛云最终返回給上传端（在指定 returnUrl 时是携带在跳转路径参数中）的数据。支持魔法变量和自定义变量。
	// returnBody 要求是合法的 JSON 文本。
	// 例如 {“key”: $(key), “hash”: $(etag), “w”: $(imageInfo.width), “h”: $(imageInfo.height)}。
	ReturnBody string `json:"returnBody,omitempty"`

	// 上传成功后，七牛云向业务服务器发送 POST 请求的 URL。必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL。
	// 另外，为了给客户端有一致的体验，我们要求 callbackUrl 返回包 Content-Type 为 “application/json”，即返回的内容必须是合法的
	// JSON 文本。出于高可用的考虑，本字段允许设置多个 callbackUrl（用英文符号 ; 分隔），在前一个 callbackUrl 请求失败的时候会依次
	// 重试下一个 callbackUrl。一个典型例子是：http://<ip1>/callback;http://<ip2>/callback，并同时指定下面的 callbackHost 字段。
	// 在 callbackUrl 中使用 ip 的好处是减少对 dns 解析的依赖，可改善回调的性能和稳定性。指定 callbackUrl，必须指定 callbackbody，
	// 且值不能为空。
	CallbackURL string `json:"callbackUrl,omitempty"`

	// 上传成功后，七牛云向业务服务器发送回调通知时的 Host 值。与 callbackUrl 配合使用，仅当设置了 callbackUrl 时才有效。
	CallbackHost string `json:"callbackHost,omitempty"`

	// 上传成功后，七牛云向业务服务器发送 Content-Type: application/x-www-form-urlencoded 的 POST 请求。业务服务器可以通过直接读取
	// 请求的 query 来获得该字段，支持魔法变量和自定义变量。callbackBody 要求是合法的 url query string。
	// 例如key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)。如果callbackBodyType指定为application/json，
	// 则callbackBody应为json格式，例如:{“key”:"$(key)",“hash”:"$(etag)",“w”:"$(imageInfo.width)",“h”:"$(imageInfo.height)"}。
	CallbackBody string `json:"callbackBody,omitempty"`

	// 上传成功后，七牛云向业务服务器发送回调通知 callbackBody 的 Content-Type。默认为 application/x-www-form-urlencoded，也可设置
	// 为 application/json。
	CallbackBodyType string `json:"callbackBodyType,omitempty"`

	// 资源上传成功后触发执行的预转持久化处理指令列表。fileType=2或3（上传归档存储或深度归档存储文件）时，不支持使用该参数。支持魔法变量和自
	// 定义变量。每个指令是一个 API 规格字符串，多个指令用;分隔。请参阅persistenOps详解与示例。同时添加 persistentPipeline 字段，使用专
	// 用队列处理，请参阅persistentPipeline。
	PersistentOps string `json:"persistentOps,omitempty"`

	// 接收持久化处理结果通知的 URL。必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL。该 URL 获取的内容和持久化处
	// 理状态查询的处理结果一致。发送 body 格式是 Content-Type 为 application/json 的 POST 请求，需要按照读取流的形式读取请求的 body
	// 才能获取。
	PersistentNotifyURL string `json:"persistentNotifyUrl,omitempty"`

	// 转码队列名。资源上传成功后，触发转码时指定独立的队列进行转码。为空则表示使用公用队列，处理速度比较慢。建议使用专用队列。
	PersistentPipeline string `json:"persistentPipeline,omitempty"`

	// saveKey 的优先级设置。为 true 时，saveKey不能为空，会忽略客户端指定的key，强制使用saveKey进行文件命名。参数不设置时，
	// 默认值为false
	ForceSaveKey bool `json:"forceSaveKey,omitempty"` //

	// 自定义资源名。支持魔法变量和自定义变量。forceSaveKey 为false时，这个字段仅当用户上传的时候没有主动指定 key 时起作用；
	// forceSaveKey 为true时，将强制按这个字段的格式命名。
	SaveKey string `json:"saveKey,omitempty"`

	// 限定上传文件大小最小值，单位Byte。小于限制上传文件大小的最小值会被判为上传失败，返回 403 状态码
	FsizeMin int64 `json:"fsizeMin,omitempty"`

	// 限定上传文件大小最大值，单位Byte。超过限制上传文件大小的最大值会被判为上传失败，返回 413 状态码。
	FsizeLimit int64 `json:"fsizeLimit,omitempty"`

	// 开启 MimeType 侦测功能，并按照下述规则进行侦测；如不能侦测出正确的值，会默认使用 application/octet-stream 。
	// 设为非 0 值，则忽略上传端传递的文件 MimeType 信息，并按如下顺序侦测 MimeType 值：
	// 1. 侦测内容； 2. 检查文件扩展名； 3. 检查 Key 扩展名。
	// 默认设为 0 值，如上传端指定了 MimeType 则直接使用该值，否则按如下顺序侦测 MimeType 值：
	// 1. 检查文件扩展名； 2. 检查 Key 扩展名； 3. 侦测内容。
	DetectMime uint8 `json:"detectMime,omitempty"`

	// 限定用户上传的文件类型。指定本字段值，七牛服务器会侦测文件内容以判断 MimeType，再用判断值跟指定值进行匹配，匹配成功则允许上传，匹配失败则返回 403 状态码。示例：
	// image/* 表示只允许上传图片类型
	// image/jpeg;image/png 表示只允许上传 jpg 和 png 类型的图片
	// !application/json;text/plain 表示禁止上传 json 文本和纯文本。注意最前面的感叹号！
	MimeLimit string `json:"mimeLimit,omitempty"`

	// 资源的存储类型，0表示标准存储，1 表示低频存储，2 表示归档存储，3 表示深度归档存储。
	FileType int `json:"fileType,omitempty"`

	CallbackFetchKey uint8 `json:"callbackFetchKey,omitempty"`

	DeleteAfterDays int `json:"deleteAfterDays,omitempty"`
}

func (*PutPolicy) UploadToken 

func (p *PutPolicy) UploadToken(cred *auth.Credentials) string

UploadToken 方法用来进行上传凭证的生成 该方法生成的过期时间是现对于现在的时间

type PutRet 

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

PutRet 为七牛标准的上传回复内容。 如果使用了上传回调或者自定义了returnBody，那么需要根据实际情况，自己自定义一个返回值结构体

type Region 

type Region struct {
	// 上传入口
	SrcUpHosts []string `json:"src_up,omitempty"`

	// 加速上传入口
	CdnUpHosts []string `json:"cdn_up,omitempty"`

	// 获取文件信息入口
	RsHost string `json:"rs,omitempty"`

	// bucket列举入口
	RsfHost string `json:"rsf,omitempty"`

	ApiHost string `json:"api,omitempty"`

	// 存储io 入口
	IovipHost string `json:"io,omitempty"`

	// 源站下载入口
	IoSrcHost string `json:"io_src,omitempty"`
}

func GetRegion 

func GetRegion(ak, bucket string) (*Region, error)

GetRegion 用来根据ak和bucket来获取空间相关的机房信息 延用 v2, v2 结构和 v4 结构不同且暂不可替代 Deprecated 使用 GetRegionWithOptions 替换

func GetRegionWithOptions 

func GetRegionWithOptions(ak, bucket string, options UCApiOptions) (*Region, error)

GetRegionWithOptions 用来根据ak和bucket来获取空间相关的机房信息

func (*Region) GetIoHost 

func (r *Region) GetIoHost(useHttps bool) string

获取io host

func (*Region) GetRsfHost 

func (r *Region) GetRsfHost(useHttps bool) string

获取rsfHost

type UCApiOptions 

type UCApiOptions struct {
	UseHttps bool //
	RetryMax int  // 单域名重试次数
	// 主备域名冻结时间（默认：600s），当一个域名请求失败（单个域名会被重试 TryTimes 次），会被冻结一段时间，使用备用域名进行重试，在冻结时间内，域名不能被使用，当一个操作中所有域名竣备冻结操作不在进行重试，返回最后一次操作的错误。
	HostFreezeDuration time.Duration
}

func DefaultUCApiOptions 

func DefaultUCApiOptions() UCApiOptions

type UcQueryIo 

type UcQueryIo = UcQueryServerInfo

type UcQueryRet 

type UcQueryRet struct {
	TTL       int                            `json:"ttl"`
	Io        map[string]map[string][]string `json:"-"`
	IoInfo    map[string]UcQueryIo           `json:"io"`
	IoSrcInfo map[string]UcQueryIo           `json:"io_src"`
	Up        map[string]UcQueryUp           `json:"up"`
	RsInfo    map[string]UcQueryServerInfo   `json:"rs"`
	RsfInfo   map[string]UcQueryServerInfo   `json:"rsf"`
	ApiInfo   map[string]UcQueryServerInfo   `json:"api"`
}

UcQueryRet 为查询请求的回复

type UcQueryServerInfo 

type UcQueryServerInfo struct {
	Main   []string `json:"main,omitempty"`
	Backup []string `json:"backup,omitempty"`
	Info   string   `json:"info,omitempty"`
}

UcQueryServerInfo 为查询请求回复中的上传域名信息

type UcQueryUp 

type UcQueryUp = UcQueryServerInfo

type Zone 

type Zone = Region

Zone 是Region的别名 兼容保留

func GetZone 

func GetZone(ak, bucket string) (zone *Zone, err error)

GetZone 用来根据ak和bucket来获取空间相关的机房信息 新版本使用GetRegion, 这个函数用来保持兼容

Source Files

View all Source files

Directories

Path Synopsis
Package log只是SDK本身自己使用，用来调试代码使用，比如输出HTTP请求和响应信息
 Package log只是SDK本身自己使用，用来调试代码使用，比如输出HTTP请求和响应信息

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.