/go-sdk

UPYUN Go SDK

Primary LanguageGoMIT LicenseMIT

UPYUN Go SDK

API Reference GitHub tag (latest by date) Build Lint Test Go Report Card Sourcegraph

import "github.com/upyun/go-sdk/v3/upyun/"

又拍云 Go SDK, 集成:

Table of Contents

Projects using this SDK

Usage

快速上手

package main

import (
    "fmt"
    "github.com/upyun/go-sdk/v3/upyun"
)

func main() {
    up := upyun.NewUpYun(&upyun.UpYunConfig{
        Bucket:   "demo",
        Operator: "op",
        Password: "password",
    })

    // 上传文件
    fmt.Println(up.Put(&upyun.PutObjectConfig{
        Path:      "/demo.log",
        LocalPath: "/tmp/upload",
    }))

    // 断点续传 文件大于 10M 才会分片
    resume := &MemoryRecorder{}
    // 若设置为 nil,则为正常的分片上传
    up.SetRecorder(resume)
    fmt.Println(up.Put(&upyun.PutObjectConfig{
        Path:      "/demo.log",
        LocalPath: "/tmp/upload",
        UseResumeUpload: true,
    }))

    // 下载
    fmt.Println(up.Get(&upyun.GetObjectConfig{
        Path:      "/demo.log",
        LocalPath: "/tmp/download",
    }))

    // 列目录
    objsChan := make(chan *upyun.FileInfo, 10)
    go func() {
        fmt.Println(up.List(&upyun.GetObjectsConfig{
            Path:        "/",
            ObjectsChan: objsChan,
        }))
    }()

    for obj := range objsChan {
        fmt.Println(obj)
    }
}

初始化 UpYun

func NewUpYun(config *UpYunConfig) *UpYun

NewUpYun 初始化 UpYunUpYun 是调用又拍云服务的统一入口,UpYun 对所有开放的接口都做了支持。


又拍云 REST API 接口

获取空间存储使用量

func (up *UpYun) Usage() (n int64, err error)

创建目录

func (up *UpYun) Mkdir(path string) error

上传

func (up *UpYun) Put(config *PutObjectConfig) (err error)

下载

func (up *UpYun) Get(config *GetObjectConfig) (fInfo *FileInfo, err error)

删除

func (up *UpYun) Delete(config *DeleteObjectConfig) error

移动

func (up *UpYun) Move(config *MoveObjectConfig) error

复制

func (up *UpYun) Copy(config *CopyObjectConfig) error

获取文件信息

func (up *UpYun) GetInfo(path string) (*FileInfo, error)

获取文件列表

func (up *UpYun) List(config *GetObjectsConfig) error

获取断点续传进度

func (up *UpYun) GetResumeProcess(path string) (*ResumeProcessResult, error)

又拍云缓存刷新接口

func (u *UpYun) Purge(urls []string) (string, error)

又拍云表单上传接口

func (up *UpYun) FormUpload(config *FormUploadConfig) (*FormUploadResp, error)

又拍云处理接口

提交处理任务

func (up *UpYun) CommitTasks(config *CommitTasksConfig) (taskIds []string, err error)

tasksIds 是提交任务的编号。通过这个编号,可以查询到处理进度以及处理结果等状态。

获取处理进度

func (up *UpYun) GetProgress(taskIds []string) (result map[string]int, err error)

获取处理结果

func (up *UpYun) GetResult(taskIds []string) (result map[string]interface{}, err error)

提交同步处理任务

func (up *UpYun) CommitSyncTasks(commitTask interface{}) (result map[string]interface{}, err error)

基本类型

UpYun

type UpYunConfig struct {
        Bucket    string                // 云存储服务名(空间名)
        Operator  string                // 操作员
        Password  string                // 密码
        Secret    string                // 表单上传密钥,已经弃用!
        Hosts     map[string]string     // 自定义 Hosts 映射关系
        UserAgent string                // HTTP User-Agent 头,默认 "UPYUN Go SDK V2"
        UseHTTP   bool                  // 默认使用https,若要使用http,则该字段值为true
}

UpYunConfig 提供初始化 UpYun 的所需参数。 需要注意的是,Secret 表单密钥已经弃用,如果一定需要使用,需调用 UseDeprecatedApi

FileInfo

type FileInfo struct {
        Name        string              // 文件名
        Size        int64               // 文件大小, 目录大小为 0
        ContentType string              // 文件 Content-Type
        IsDir       bool                // 是否为目录
        MD5         string              // MD5 值
        Time        time.Time           // 文件修改时间

        Meta map[string]string          // Metadata 数据
}

FormUploadResp

type FormUploadResp struct {
        Code      int      `json:"code"`            // 状态码
        Msg       string   `json:"message"`         // 状态信息
        Url       string   `json:"url"`             // 保存路径
        Timestamp int64    `json:"time"`            // 时间戳
        ImgWidth  int      `json:"image-width"`     // 图片宽度
        ImgHeight int      `json:"image-height"`    // 图片高度
        ImgFrames int      `json:"image-frames"`    // 图片帧数
        ImgType   string   `json:"image-type"`      // 图片类型
        Sign      string   `json:"sign"`            // 签名
        Taskids   []string `json:"task_ids"`        // 异步任务
}

FormUploadResp 为表单上传的返回内容的格式。其中 Code 字段为状态码,可以查看 API 错误码表

PutObjectConfig

type PutObjectConfig struct {
        Path              string                // 云存储中的路径
        LocalPath         string                // 待上传文件在本地文件系统中的路径
        Reader            io.Reader             // 待上传的内容
        Headers           map[string]string     // 额外的 HTTP 请求头
        UseMD5            bool                  // 是否需要 MD5 校验
        UseResumeUpload   bool                  // 是否使用断点续传
        AppendContent     bool                  // 是否需要追加文件内容
        ResumePartSize    int64                 // 断点续传块大小
        MaxResumePutTries int                   // 断点续传最大重试次数
}

PutObjectConfig 提供上传单个文件所需的参数。有几点需要注意:

  • LocalPathReader 是互斥的关系,如果设置了 LocalPath,SDK 就会去读取这个文件,而忽略 Reader 中的内容。
  • 如果 Reader 是一个流/缓冲等的话,需要通过 Headers 参数设置 Content-Length,SDK 默认会对 *os.File 增加该字段。
  • 断点续传的上传内容类型必须是 *os.File, 断点续传会将文件按照 ResumePartSize 进行切割,然后按次序一块一块上传,如果遇到网络问题,会进行重试,重试 MaxResumePutTries 次,默认无限重试。
  • AppendContent 如果是追加文件的话,确保非最后的分片必须为 1M 的整数倍。
  • 如果需要 MD5 校验,SDK 对 *os.File 会自动计算 MD5 值,其他类型需要自行通过 Headers 参数设置 Content-MD5

GetObjectConfig

type GetObjectConfig struct {
        Path      string                    // 云存储中的路径
        Headers   map[string]string         // 额外的 HTTP 请求头
        LocalPath string                    // 本地文件路径
        Writer    io.Writer                 // 保存内容的容器
}

GetObjectConfig 提供下载单个文件所需的参数。 跟 PutObjectConfig 类似,LocalPathWriter 是互斥的关系,如果设置了 LocalPath,SDK 就会把内容写入到这个文件中,而忽略 Writer

GetObjectsConfig

type GetObjectsConfig struct {
        Path           string                   // 云存储中的路径
        Headers        map[string]string        // 额外的 HTTP 请求头
        ObjectsChan    chan *FileInfo           // 对象通道
        QuitChan       chan bool                // 停止信号
        MaxListObjects int                      // 最大列对象个数
        MaxListTries   int                      // 列目录最大重试次数
        MaxListLevel int                        // 递归最大深度
        DescOrder bool                          // 是否按降序列取,默认为升序

        // Has unexported fields.
}

GetObjectsConfig 提供列目录所需的参数。当列目录结束后,SDK 会将 ObjectsChan 关闭掉。

ListObjectsConfig

type ListObjectsConfig struct {
	Path         string            // 文件夹路径
	Headers      map[string]string // 请求头
	Iter         string            // 下次遍历目录的开始位置,第一次不需要输入,之后每次返回结果时会返回当前结束的位置, 即下次开始的位置
	MaxListTries int               // 重试的次数最大值 默认5次
	DescOrder    bool              // 正序or倒叙
	Limit        int               // 每次遍历的文件个数,默认256 最大值4096

	// Has unexported fields.
}

ListObjectsConfig 提供给列目录并且需要手动分页的场景, 见 upyun/reset_test.go 函数 TestListObjects

DeleteObjectConfig

type DeleteObjectConfig struct {
        Path  string        // 云存储中的路径
        Async bool          // 是否使用异步删除
}

DeleteObjectConfig 提供删除单个文件/空目录所需的参数。

MoveObjectConfig

type MoveObjectConfig struct {
        SrcPath  string             // 移动源路径
        DestPath string             // 目的路径
        Headers  map[string]string  // 额外的 HTTP 请求头
}

MoveObjectConfig 提供单个文件移动。

CopyObjectConfig

type CopyObjectConfig struct {
        SrcPath  string             // 复制源路径
        DestPath string             // 目的路径
        Headers  map[string]string  // 额外的 HTTP 请求头
}

CopyObjectConfig 提供单个文件复制。

FormUploadConfig

type FormUploadConfig struct {
        LocalPath      string                       // 待上传的文件路径
        SaveKey        string                       // 保存路径
        ExpireAfterSec int64                        // 签名超时时间
        NotifyUrl      string                       // 结果回调地址
        Apps           []map[string]interface{}     // 异步处理任务
        Options        map[string]interface{}       // 更多自定义参数
}

FormUploadConfig 提供表单上传所需的参数。

CommitTasksConfig

type CommitTasksConfig struct {
        AppName   string                            // 异步任务名称
        NotifyUrl string                            // 回调地址
        Tasks     []interface{}                     // 任务数组

        // Naga 相关配置
        Accept    string                            // 回调支持的类型,默认为 json
        Source    string                            // 处理原文件路径
}

CommitTasksConfig 提供提交异步任务所需的参数。AcceptSource 仅与异步音视频处理有关。Tasks 是一个任务数组,数组中的每一个元素都是任务相关的参数(一般情况下为字典类型)。

BreakPointConfig

type BreakPointConfig struct {
        UploadID    string
        PartID      int  // 失败待上传的 PartID
        PartSize    int64
        FileSize    int64
        FileModTime time.Time
        LastTime    time.Time  
}

BreakPointConfig 提供续传所需的参数,在使用 Put 进行断点续传时,首先使用 UpYunSetRecorder 传入一个 Recorder 接口类型(内部使用 MemoryRecorder 实现了该接口),当出现上传失败的时候,调用 UpYun 下的 RecorderGet 方法,即可获取当前断点的相关信息。

LiveauditCreateTask

type LiveauditCreateTask struct {
	Source    string
	SaveAs    string
	NotifyUrl string
	Interval  string
	Resize    string
}

LiveauditCreateTask 提供视频直播内容识别任务创建所需参数,适用于 CommitSyncTasks

LiveauditCancelTask

type LiveauditCancelTask struct {
	TaskId string
}

LiveauditCancelTask 提供视频直播内容识别任务取消所需参数,适用于 CommitSyncTasks

SyncCommonTask

type SyncCommonTask struct {
        Kwargs  map[string]interface{}
        TaskUri string
}

SyncCommonTask 提供同步任务所需的参数,适用于 CommitSyncTasks。有几点需要注意:

  • 使用 p1.api.upyun.com 同步任务接口,如果没有提供单独的接口,请使用 SyncCommonTask
  • Kwargs 为请求参数。
  • TaskUri 为任务 uri,不包括服务名,例如 /liveaudit/create