UPYUN Java SDK
Maven 安装
com.upyun
java-sdk
3.7
更新说明
使用1.0.x系列版本 SDK 的用户,注意原有部分方法已经不再推荐使用,但是出于兼容考虑目前任然保留,建议更新升级程序使用新版 SDK 提供的方法。
目录
云存储基础接口
初始化 UpYun
UpYun upyun = new UpYun("空间名称", "操作员名称", "操作员密码");
可选属性:
是否开启 debug 模式:默认不开启
upyun.setDebug(true);
手动设置超时时间:默认为30秒
upyun.setTimeout(60);
选择最优的接入点
upyun.setApiDomain(UpYun.ED_AUTO);
根据国内的网络情况,又拍云存储 API 目前提供了电信、联通网通、移动铁通三个接入点。可以通过setApiDomain()方法进行设置,默认将根据网络条件自动选择接入点。
接入点有四个值可选:
UpYun.ED_AUTO //根据网络条件自动选择接入点
UpYun.ED_TELECOM //电信接入点
UpYun.ED_CNC //联通网通接入点
UpYun.ED_CTT //移动铁通接入点
**注:**建议大家根据服务器网络状况,手动设置合理的接入点已获取最佳的访问速度
创建目录
方法原型:
public boolean mkDir(String path, boolean auto);
参数说明:
path目录路径,以/结尾
auto(可选):若为 true 则自动创建父级目录(只支持自动创建10级以内的父级目录)
返回值说明:
结果为 true 创建目录成功
若空间相同目录下已经存在同名的文件,则将返回『不允许创建目录』的错误
举例说明:
String path = "/dir1/dir2/";
// 创建目录,自动创建父级目录
boolean result = upyun.mkDir(path, true);
删除目录
方法原型:
public boolean rmDir(String path);
参数说明:
path目录路径
返回值说明:
结果为 true 删除目录成功
若待删除的目录 path 下还存在任何文件或子目录,将返回『不允许删除』的错误
举例说明:
String path = "/dir1/dir2/";
// 删除目录
boolean result = upyun.rmDir(path);
获取目录文件列表
方法原型:
public List readDir(String path);
UpYun.FolderItem 包含属性:
name 文件名
type 文件类型
size 文件大小
date 文件创建日期
以上属性作用域皆为 public,可直接调用
参数说明:
path 目录路径
返回值说明:
若 path 目录没有内容时,返回null
若 path 目录不存在时,则将返『不存在目录』的错误
举例说明:
String path = "/dir1/";
// 获取目录中文件列表
List items = upyun.readDir(path);
for (int i = 0; i < items.size(); i++) {
System.out.println(items.get(i));
}
上传文件
方法原型:
public boolean writeFile(String filePath, String datas, boolean auto);
public boolean writeFile(String filePath, File file, boolean auto);
public boolean writeFile(String filePath, byte[] datas, boolean auto);
参数说明:
filePath 保存到又拍云存储的文件路径,以/开始
第二个参数 接受 String 、 File 和 byte[] 三种类型的数据
auto (可选):若为 true 则自动创建父级目录(只支持自动创建10级以内的父级目录)
返回值说明:
结果为 true 上传文件成功
可选属性:
上传文件时可进行文件的 MD5 校验,若又拍云服务端收到的文件MD5值与用户设置的不一致,将返回 406 Not Acceptable 错误。对于需要确保上传文件的完整性要求的业务,可以设置该参数:
upyun.setContentMD5(UpYun.md5(file));
举例说明:
// 例1:上传纯文本内容,自动创建父级目录
String str = "Hello UpYun";
boolean result = upyun.writeFile("/path/to/file", str, true);
// 例2:采用数据流模式上传文件(节省内存),自动创建父级目录
File file = new File(localFilePath);
upyun.setContentMD5(UpYun.md5(file));
boolean result = upyun.writeFile(filePath, file, true);
注:
若空间内指定目录已存在相同文件,则会被覆盖,且不可逆。若要避免此情况,可以先通过获取文件信息来判断是否已经存在相同文件
获取文件信息
方法原型:
public Map getFileInfo(String filePath);
参数说明:
filePath 又拍云中文件的路径
返回值说明:
若 filePath 所指定文件不存在,则直接返回 null
Map 包含3个Key:
type 文件类型
size 文件大小
date 创建日期
举例说明:
String filePath = "/path/to/file";
// 获取文件信息
Map info = upyun.getFileInfo(filePath);
String type = info.get("type");
String size = info.get("size");
String date = info.get("date");
获取使用量信息
方法原型:
public long getBucketUsage();
public long getFolderUsage(String path);
举例说明:
// 例1:获取整个空间的使用量情况
long usage = upyun.getBucketUsage();
// 例2:获取某个目录的使用量情况
long usage = upyun.getFolderUsage(dir);
返回值说明:
返回值单位为 Byte
下载文件
方法原型:
public String readFile(String filePath);
public boolean readFile(String filePath, File file);
参数说明:
filePath 文件在又拍云存储中的路径
file 本地临时文件(用来保存下载下来的数据)
返回值说明:
方法一:文本内容
方法二:结果为 true 下载成功
举例说明:
// 例1:直接读取文本内容
String remoteFilePath = "/path/to/file";
String datas = upyun.readFile(remoteFilePath);
// 例2:下载文件,采用数据流模式下载文件(节省内存)
String remoteFilePath = "/path/to/file";
File file = new File(localFilePath); // 创建一个本地临时文件
boolean result = upyun.readFile(remoteFilePath, file);
删除文件
方法原型:
public boolean deleteFile(String filePath);
参数说明:
filePath 文件在又拍云的路径
返回值说明:
若 filePath 指定的文件不存在,则返回『文件不存在』的错误
结果为 true 删除文件成功
举例说明:
String filePath = "/path/to/file";
// 删除文件
boolean result = upyun.deleteFile(filePath);
图片处理接口
方法原型:
public boolean writeFile(String filePath, File file, boolean auto, Map params);
public boolean writeFile(String filePath, byte[] datas, boolean auto, Map params);
public boolean writeFile(String filePath, String datas, boolean auto, Map params);
参数说明:
filePath 保存到又拍云存储的路径
第二个参数 接受 String 、File 和 byte[] 三种类型的图片数据内容
auto (可选):自动创建父级目录(只支持自动创建10级以内的父级目录)
params 自定义图片处理参数的组合,详情请看params参数说明
返回值说明:
结果为 true 图片上传并处理成功
图片处理包括『制作图片缩略图』,『图片裁剪』,『图片旋转』。只需要选则不同的 PARAMS 参数就可以分别完成这些操作,下面分别举例说明。
制作图片缩略图
举例说明:
Map params = new HashMap();
// 设置缩略图类型
params.put(PARAMS.KEY_X_GMKERL_TYPE.getValue(), PARAMS.VALUE_FIX_BOTH.getValue());
// 设置缩略图参数值
params.put(PARAMS.KEY_X_GMKERL_VALUE.getValue(), "150x150");
// 设置缩略图的质量,默认 95
params.put(PARAMS.KEY_X_GMKERL_QUALITY.getValue(), "95");
// 待上传的图片文件
File file = new File(localFilePath);
String filePath = "/path/to/file";
// 上传图片,并同时进行图片处理
boolean result = upyun.writeFile(filePath, file, true, params);
图片裁剪
举例说明:
// 设置缩略图的参数
Map params = new HashMap();
// 设置图片裁剪,参数格式:x,y,width,height
params.put(PARAMS.KEY_X_GMKERL_CROP.getValue(), "0,0,100,100");
// 待上传的图片文件
File file = new File(localFilePath);
// 上传图片,并同时进行图片处理
boolean result = upyun.writeFile(savePath, file, autoMkDir, params);
图片旋转
举例说明:
// 设置缩略图的参数
Map params = new HashMap();
// 设置图片旋转
params.put(PARAMS.KEY_X_GMKERL_ROTATE.getValue(), PARAMS.VALUE_ROTATE_90.getValue());
// 待上传的图片文件
File file = new File(localFilePath);
// 上传图片,并同时进行图片处理
boolean result = upyun.writeFile(savePath, file, autoMkDir, params);
表单上传接口
初始化 FormUploader
FormUploader uploader = new FormUploader(BUCKET_NAME, APIKEY, null);
FormUploader uploader = new FormUploader(BUCKET_NAME, null, signatureListener);
参数说明:
BUCKET_NAME 空间名
APIKEY 表单密匙
signatureListener 签名回调
两种初始化方法任选一种,可以将表单密匙保存在本地,也可在签名回调中访问服务器获取签名。
signatureListener 回调接口规则如下:
SignatureListener signatureListener=new SignatureListener() {
@Override
public String getSignature(String raw) {
return UpYunUtils.md5(raw+KEY);
}
};
将参数 raw 传给后台服务器和表单密匙连接后做一次 md5 运算返回结果。
可选属性:
手动设置超时时间:默认为30秒
public void setTimeout(int timeout)
选择最优的接入点,默认 v0.api.upyun.com
public void setApiDomain(String domain)
选择默认过期时间,默认1800秒
public void setExpiration(int expiration)
表单上传文件
方法原型:
public Result upload(Map params, File file)
public Result upload(Map params, byte[] datas)
参数说明:
params 参数键值对
file 上传文件
datas 上传数组
参数键值对中 Params.SAVE_KEY 为必选参数,其他可选参数见 Params 或者官网 API 文档。
返回说明:
Result.Succeed 是否成功
Result.code 返回http消息码
Result.msg 返回消息
举例说明:
###表单上传作图
上传同步作图
private static void testSync() {
//初始化uploader
FormUploader uploader = new FormUploader(BUCKET_NAME, APIKEY, null);
//初始化参数组 Map
final Map paramsMap = new HashMap();
//添加 SAVE_KEY 参数
paramsMap.put(Params.SAVE_KEY, savePath);
//添加同步上传作图参数 X_GMKERL_THUMB
paramsMap.put(Params.X_GMKERL_THUMB, "/fw/300/unsharp/true/quality/80/format/png");
//打印结果
System.out.println(uploader.upload(paramsMap, file));
}
paramsMap 添加键值对,Params.X_GMKERL_THUMB 为 key,作图规则见上传作图 API
上传异步作图
private static void testAsync() {
//uploader
FormUploader uploader = new FormUploader(BUCKET_NAME, APIKEY, null);
//初始化参数组 Map
final Map paramsMap = new HashMap();
//添加 SAVE_KEY 参数
paramsMap.put(Params.SAVE_KEY, savePath);
//初始化JSONArray
JSONArray array = new JSONArray();
//初始化JSONObject
JSONObject json = new JSONObject();
//json 添加 name 属性
json.put("name", "thumb");
//json 添加 X_GMKERL_THUMB 属性
json.put(Params.X_GMKERL_THUMB, "/fw/300/unsharp/true/quality/80/format/png");
//json 添加 save_as 属性
json.put("save_as", "/path/to/fw_100.jpg");
//json 添加 notify_url 属性
json.put("notify_url","http://httpbin.org/post");
//将json 对象放入 JSONArray
array.put(json);
//添加异步作图参数 APPS
paramsMap.put(Params.APPS, array);
//打印结果
System.out.println(uploader.upload(paramsMap, file));
}
paramsMap 添加键值对,Params.APPS 为 key,作图规则见上传作图 API
异步音视频处理
初始化 MediaHandler
MediaHandler handle = new MediaHandler(BUCKET_NAME, OPERATOR_NAME, OPERATOR_PWD);
参数说明:
BUCKET_NAME 空间名
OPERATOR_NAME 操作员名称
OPERATOR_PWD 操作员密码
可选属性:
手动设置超时时间:默认为30秒
public void setTimeout(int timeout)
发起异步处理请求
方法原型:
public Result process(Map params) throws IOException
参数说明:
params 参数键值对
返回说明:
Result.Succeed 是否成功
Result.code 返回http消息码
Result.msg 返回消息
举例说明:
查询处理进度
方法原型:
public Result getStatus(Map params) throws IOException
参数说明:
params 参数键值对 包括 bucket_name 和 task_ids
返回说明:
同上
举例说明:
查询处理结果
方法原型:
public Result getResult(Map params) throws IOException
参数说明:
同上
返回说明:
同上
举例说明:
##错误说明