UPYUN Go SDK

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

又拍云 Go SDK, 集成：

• 又拍云 HTTP REST 接口
• 又拍云 HTTP FORM 接口
• 又拍云缓存刷新接口
• 又拍云视频处理接口

Table of Contents

• UPYUN Go SDK
  • Projects using this SDK
  • Usage
    • 快速上手
    • 初始化 UpYun
    • 又拍云 REST API 接口
      • 获取空间存储使用量
      • 创建目录
      • 上传
      • 下载
      • 删除
      • 移动
      • 复制
      • 获取文件信息
      • 获取文件列表
      • 获取断点续传进度
    • 又拍云缓存刷新接口
    • 又拍云表单上传接口
    • 又拍云处理接口
      • 提交处理任务
      • 获取处理进度
      • 获取处理结果
      • 提交同步处理任务
    • 基本类型
      • UpYun
      • FileInfo
      • FormUploadResp
      • PutObjectConfig
      • GetObjectConfig
      • GetObjectsConfig
      • DeleteObjectConfig
      • MoveObjectConfig
      • CopyObjectConfig
      • FormUploadConfig
      • CommitTasksConfig
      • BreakPointConfig
      • LiveauditCreateTask
      • LiveauditCancelTask
      • SyncCommonTask

Projects using this SDK

• 又拍云命令行工具 by polym

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 初始化 UpYun，UpYun 是调用又拍云服务的统一入口，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 提供上传单个文件所需的参数。有几点需要注意:

• LocalPath 跟 Reader 是互斥的关系，如果设置了 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 类似，LocalPath 跟 Writer 是互斥的关系，如果设置了 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 提供提交异步任务所需的参数。Accept 跟 Source 仅与异步音视频处理有关。Tasks 是一个任务数组，数组中的每一个元素都是任务相关的参数（一般情况下为字典类型）。

BreakPointConfig

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

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

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。