ufsdk

UCloud 对象存储 SDK

Modules are interface and implementation.
The best modules are where interface is much simpler than implementation.
By: John Ousterhout

Table of Contents

• 概述
  • US3 对象存储基本概念
  • 签名
• 快速使用
  • 下载安装
    • 环境要求
    • SDK下载
    • 配置文件
  • 执行测试
• 示例代码
  • 存储空间管理
  • 对象/文件管理
    • 普通上传
    • 表单上传
    • 秒传
    • 流式上传
    • 分片上传
    • 上传回调
    • 文件下载
    • 查询文件基本信息
    • 删除文件
    • 文件解冻
    • 文件存储类型转换
    • 比较本地文件和远程文件etag
    • 文件拷贝
    • 文件重命名
    • 前缀列表查询
    • 获取目录文件列表
• 文档说明
• 联系我们

概述

US3 对象存储基本概念

在对象存储系统中，存储空间（Bucket）是文件（File）的组织管理单位，文件（File）是存储空间的逻辑存储单元。对于每个账号，该账号里存放的每个文件都有唯一的一对存储空间（Bucket）与键（Key）作为标识。我们可以把 Bucket 理解成一类文件的集合，Key 理解成文件名。由于每个 Bucket 需要配置和权限不同，每个账户里面会有多个 Bucket。在 US3 里面，Bucket 主要分为公有和私有两种，公有 Bucket 里面的文件可以对任何人开放，私有 Bucket 需要配置对应访问签名才能访问。

签名

本 SDK 接口是基于 HTTP 的，为了连接的安全性，US3 使用 HMAC SHA1 对每个连接进行签名校验。使用本 SDK 可以忽略签名相关的算法过程，只要把公私钥写入到配置文件里面，读取并传给 UFileRequest 里面的 New 方法即可。签名相关的算法与详细实现请见 Auth 模块

快速使用

下载安装

环境要求

• Golang 版本 (待校验)

SDK下载

• 快速安装：go get github.com/ufilesdk-dev/ufile-gosdk
• 历史版本下载

配置文件

• 进入目录 github.com/ufilesdk-dev/ufile-gosdk 下，按说明填写 config.json

{
    "说明1":"管理 bucket 创建和删除必须要公私钥(见 https://console.ucloud.cn/uapi/apikey)，如果只做文件上传和下载用 TOEKN (见 https://console.ucloud.cn/ufile/token)就够了，为了安全，强烈建议只使用 TOKEN 做文件管理",
    "public_key":"",
    "private_key":"",

    "说明2":"以下两个参数是用来管理文件用的。对应的是 file.go 里面的接口，file_host 是不带 bucket 名字的。比如：北京地域的host填cn-bj.ufileos.com，而不是填 bucketname.cn-bj.ufileos.com。若为自定义域名，请直接带上 http 开头的 URL。如：http://example.com",
    "bucket_name":"",
    "file_host":"",

    "说明3":"verifyUploadMD5 用于数据完整性校验，默认不开启，若要开启请置为true",
    "verifyUploadMD5": false
}

密钥可以在控制台中 API 产品 - API 密钥，点击显示 API 密钥获取。将 public_key 和 private_key 分别赋值给相关变量后，SDK即可通过此密钥完成鉴权。请妥善保管好 API 密钥，避免泄露。 token（令牌）是针对指定bucket授权的一对公私钥。可通过token进行授权bucket的权限控制和管理。可以在控制台中对象存储US3-令牌管理，点击创建令牌获取。

运行demo

• 目录 github.com/ufilesdk-dev/ufile-gosdk 下执行go run demo.go

导入使用

在您的项目代码中，使用import ufsdk "github.com/ufilesdk-dev/ufile-gosdk"引入US3 Go SDK的包

示例代码

存储空间管理

创建存储空间

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewBucketRequest(config, nil)
if err != nil {
	panic(err.Error())
}

bucketRet, err := req.CreateBucket("BucketName", "Region", "BucketType", "ProjectId")
if err != nil {
	log.Fataf("创建 bucket 出错，错误信息为：%s\n", err.Error())
}

回到目录

获取存储空间信息

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewBucketRequest(config, nil)
if err != nil {
	panic(err.Error())
}

bucketList, err := req.DescribeBucket("BucketName", Offset, Limit, "ProjectId")
if err != nil {
	log.Println("获取 bucket 信息出错，错误信息为：", err.Error())
}

回到目录

更新存储空间访问类型

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewBucketRequest(config, nil)
if err != nil {
	panic(err.Error())
}

bucketRet, err = req.UpdateBucket("BucketName", "BucketType", "ProjectId")
if err != nil {
	log.Println("更新 bucket 信息失败，错误信息为：", err.Error())
}

回到目录

删除存储空间

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewBucketRequest(config, nil)
if err != nil {
	panic(err.Error())
}

bucketRet, err = req.DeleteBucket("BucketName", "ProjectId")
if err != nil {
	log.Fataf("删除 bucket 失败，错误信息为：", err.Error())
}

回到目录

对象/文件管理

普通上传

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}

err = req.PutFile("FilePath", "KeyName", "MimeType")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

表单上传

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}

err = req.PostFile("FilePath", "KeyName", "MimeType")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

秒传

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}

err = req.UploadHit("FilePath", "KeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

流式上传

• demo程序

if err != nil {
    log.Fatal(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
    log.Fatal(err.Error())
}
// 流式上传本地小文件
f, err := os.Open("FilePath")
if err != nil {
    panic(err.Error())
}
err = req.IOPut(f, "KeyName", "")
f.Close()
if err != nil {
    log.Fatalf("%s\n", req.DumpResponse(true))
}

// 流式上传大文件
f1, err := os.Open("FilePath1")
if err != nil {
    panic(err.Error())
}
err = req.IOMutipartAsyncUpload(f1, "KeyName", "")
f1.Close()
if err != nil {
    log.Fatalf("%s\n", req.DumpResponse(true))
}

回到目录

分片上传

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}

err = req.MPut("FilePath", "KeyName", "MimeType")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

上传回调

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}

// 同步分片上传回调
err = req.MPutWithPolicy("FilePath", "KeyName", "MimeType", "Policy")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

// 异步分片上传回调
err = req.AsyncMPutWithPolicy("FilePath", "KeyName", "MimeType", "Policy")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

// 异步分片并发上传回调
jobs := 20 // 并发数为 20
err = req.AsyncUploadWithPolicy("FilePath", "KeyName", "MimeType", jobs, "Policy")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文件下载

• demo程序

// 加载配置，创建请求
config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
// 普通下载
err = req.Download("DownLoadURL")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}
// 流式下载
err = req.Download("buffer", "KeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

查询文件基本信息

• demo程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.HeadFile("KeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

删除文件

• demo程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.DeleteFile("KeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文件解冻

• demo 程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.Restore("KeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文件存储类型转换

• demo 程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.ClassSwitch("KeyName", "StorageClass")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

比较本地文件和远程文件etag

• demo程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.CompareFileEtag("KeyName", "FilePath")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文件拷贝

• demo程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
err = req.Copy("DstkeyName", "SrcBucketName", "SrcKeyName")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文件重命名

• demo程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
force := true // 为true则强制重命名
err = req.Rename("KeyName", "KeyName", force)
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

前缀列表查询

• demo 程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
list, err := req.PrefixFileList("Prefix", "Marker", "Limit")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

获取目录文件列表

• demo 程序

config, err := ufsdk.LoadConfig("config.json")
if err != nil {
	panic(err.Error())
}
req, err := ufsdk.NewFileRequest(config, nil)
if err != nil {
	panic(err.Error())
}
list, err := req.ListObjects("Prefix", "Marker", "Delimiter", "MaxKeys")
if err != nil {
	log.Println("DumpResponse：", string(req.DumpResponse(true)))
}

回到目录

文档说明

本 SDK 使用 godoc 约定的方法对每个 export 出来的接口进行注释。 你可以直接访问生成好的在线文档。

联系我们

• UCloud US3 官方网站
• UCloud US3 官方文档中心
• UCloud 官方技术支持：提交工单

许可证

Apache License 2.0