UPYUN Erlang SDK
UPYUN Erlang SDK 集成:
安装说明
确保安装了 17.1 版本或以上的 Erlang/OTP 环境。
rebar.config
文件
配置 {deps, [
...
{upyun, ".*", {git, "git://github.com/upyun/erlang-sdk.git", {branch, "master"}}}
]}.
编译和测试
git clone https://github.com/upyun/erlang-sdk.git && cd erlang-sdk
./rebar3 compile
./rebar3 dialyzer
./rebar3 eunit
接口说明
所有的接口调用(特殊注明除外),成功会返回 ok
或 {ok, Result}
,失败则返回 {error, Reason}
,其中 Reason
包含了完整的 HTTP 返回请求信息,错误代码参看 API 错误码表。
用法示例参看测试文件。
初始化服务
{ok, Client} = upyun:init(Options).
参数说明:
- Options,
proplists
类型的参数:- bucket,必选,服务空间名称
- operator,必选,授权操作员帐号
- password,必选,授权操作员密码
- endpoint,网络接入点,其可选的值有:
auto
,根据网络条件自动选择接入点,默认telecom
,电信接入点cnc
,联通网通接入点ctt
,移动铁通接入点
返回值说明:
- Client,包含完整配置信息的客户端对象,
maps
类型
上传文件
ok = upyun:put(Client, Key, FileBin).
参数说明:
- Key,文件在又拍云存储服务中保存的路径
- FileBin,待上传文件的二进制数据
- Options,可选,
proplists
类型的参数:- checksum,可选,
boolean
类型,默认false
,表示不对上传的数据进行 MD5 校验 - secret,可选,指定具体密钥内容;默认
false
,表示不设置密钥。特别地,该功能仅对配置了缩略图版本号的图片空间有效 - headers,可选,根据需求设置自定义 HTTP Header,例如作图参数
x-gmkerl-*
,具体参看上传预处理(同步)
- checksum,可选,
流式上传
上传本地文件
ok = upyun:put(Client, Key, {stream, {file, FileName}}, Options).
参数说明:
- FileName,待上传文件的路径
- Options,可选,
proplists
类型的参数:- chunk_size,可选,指定数据流分块大小,默认
4M
- secret,可选,指定具体密钥内容;默认
false
,表示不设置密钥。特别地,该功能仅对配置了缩略图版本号的图片空间有效 - headers,可选,根据需求设置自定义 HTTP Header,例如作图参数
x-gmkerl-*
,具体参看上传预处理(同步)
- chunk_size,可选,指定数据流分块大小,默认
自定义上传
ok = upyun:put(Client, Key, {stream, StreamFun}, Options).
参数说明:
- StreamFun,自定义 streaming 读取函数,具体参看相关测试用例
- Options,可选,
proplists
类型的参数:- secret,可选,指定具体密钥内容;默认
false
,表示不设置密钥。特别地,该功能仅对配置了缩略图版本号的图片空间有效 - headers,可选,根据需求设置自定义 HTTP Header,例如作图参数
x-gmkerl-*
,具体参看上传预处理(同步)
- secret,可选,指定具体密钥内容;默认
断点续传
适用于上传大文件,文件在上传过程中发生异常失败时,将等待 100 毫秒后,在失败断点处自动重试 2 次。
除此之外,也提供了更加灵活的三阶段上传接口,便于自定义断点续传实现,具体参看断点续传模块。
ok = upyun:put(Client, Key, FileBin, Options).
参数说明:
- FileBin,待上传文件的二进制数据
- Options,
proplists
类型的参数:- resume,必选,值为
true
,标记此次上传为断点续传 - type,必选,MIME 文件类型,如
<<"image/jpeg">>
- checksum,可选,默认
false
,表示不对上传的数据进行 MD5 校验
- resume,必选,值为
下载文件
{ok, FileBin} = upyun:get(Client, Key).
返回值说明:
- FileBin,下载到的二进制数据
流式下载
下载到本地文件
ok = upyun:get(Client, Key, [{stream, {file, FileName}}]).
参数说明:
- FileName,文件内容写入本地文件的路径
自定义下载
ok = upyun:get(Client, Key, [{stream, StreamFun}]).
参数说明:
- StreamFun,自定义 streaming 写入函数,具体参看相关测试用例
删除文件
ok = upyun:delete(Client, Key).
同步删除有频率限制,批量删除推荐下面这个异步删除接口(无频率限制)。
ok = upyun:delete(Client, Key, true).
获取文件信息
{ok, {Type, Size, LastModified}} = upyun:getinfo(Client, Key).
返回值说明:
- Type,文件为
file
,文件夹为directory
- Size,文件大小
- LastModified,文件最后修改时间
创建目录
ok = upyun:mkdir(Client, DirKey).
参数说明:
- DirKey,待创建的目录路径
删除目录
ok = upyun:rmdir(Client, DirKey).
获取目录文件列表
{ok, {Result, Iter}} = upyun:getlist(Client, DirKey, Options).
参数说明:
- DirKey,目录路径
- Options,
proplists
类型的参数:- iter,分页开始位置,通过上次请求的返回值中获得,所以第一次请求不需要填写
- limit,获取的文件数量,默认 100,最大 10000
- order,
asc
或desc
,按最后修改时间升序或降序排列,默认asc
- timeout,可选,请求超时时间,默认 1 分钟
返回值说明:
-
Result,为当前目录下各个文件/子目录的属性及对应的值的列表,属性包括
文件名
、类型
、大小
、最后修改时间
,示例:[[{name,<<"image.jpg">>}, {type,file}, {size,2080825}, {last_modified,1486805355}], [{name,<<"dir">>}, {type,directory}, {size,0}, {last_modified,1486805355}]]
-
Iter,返回下一次分页开始位置,它由一串 Base64 编码的随机数组成,当它是
eof
时,表明本次请求已经是最后一次分页
获取空间使用情况
{ok, Result} = upyun:usage(Client).
返回值说明:
- Result,为服务的使用量(单位比特)
更新元数据
ok = upyun:metadata(Client, Key, Option, Metas).
参数说明:
- Option,原数据更新类型,其可选的值有:
merge
,合并文件元信息,相同的元信息将被新上传的值替换,默认replace
,替换文件元信息为新上传的文件元信息delete
,删除文件元信息
- Metas,
proplists
类型的元数据列表,如[{<<"Foo">>, <<"Bar">>}]
- UpdateLastModified,可选,
boolean
类型,表示是否更新文件的最后修改时间,默认false
(不更新)
缓存刷新
{ok, Result} = upyun:purge(Client, Keys).
参数说明:
- Keys,待刷新文件的 Key 列表
返回值说明:
- Result,为 JSON 字符串格式,如
{invalid_domain_of_url: 不属于自己域名的 url 列表}
错误信息及响应状态参看缓存刷新响应状态。