upyun/java-sdk

UPYUN Java SDK

UPYUN Java SDK

又拍云存储 Java SDK，基于 又拍云存储 HTTP REST API 接口 ， 又拍云 HTTP FORM API 接口 和 又拍云云处理文档 开发，适用于 Java 7 及以上版本。

Maven 安装

<dependency>
  <groupId>com.upyun</groupId>
  <artifactId>java-sdk</artifactId>
  <version>4.2.3</version>
</dependency>

目录

• 云存储基础接口
  • 初始化 RestManager
  • 创建目录
  • 删除目录
  • 获取目录文件列表
  • 上传文件
  • 获取文件信息
  • 获取使用量信息
  • 下载文件
  • 删除文件
  • 移动文件
  • 复制文件
  • 串行式断点续传
  • 并行式断点续传
• 表单上传接口
  • 初始化 FormUploader
  • 表单上传文件
  • 表单上传作图
  • 错误说明
• 云处理
  • 异步音视频处理
  • 查询处理进度
  • 查询处理结果
  • 压缩解压缩
  • 异步文件拉取
  • 文档转换
  • 图片拼接

云存储基础接口

初始化 RestManager

	RestManager manager = new RestManager("空间名称", "操作员名称", "操作员密码");

可选属性：

• 设置代理

    manager.setProxy(proxy);

• 手动设置超时时间：默认为30秒

    manager.setTimeout(60);

• 选择最优的接入点

    manager.setApiDomain(RestManager.ED_AUTO);

根据国内的网络情况，又拍云存储 API 目前提供了电信、联通网通、移动铁通三个接入点。可以通过setApiDomain()方法进行设置，默认将根据网络条件自动选择接入点。

接入点有四个值可选：

	RestManager.ED_AUTO    //根据网络条件自动选择接入点
	RestManager.ED_TELECOM //电信接入点
	RestManager.ED_CNC     //联通网通接入点
	RestManager.ED_CTT     //移动铁通接入点

**注：**建议大家根据服务器网络状况，手动设置合理的接入点已获取最佳的访问速度

---

创建目录

方法原型：

	public Response mkDir(String path);

参数说明：

• path 目录路径，以/结尾

返回值说明：

• 返回 Response

举例说明：

	String path = "/dir1/dir2/";
    // 创建目录，自动创建父级目录
    Response result = manager.mkDir(path);

---

删除目录

方法原型：

	public Response rmDir(String path);

参数说明：

• path 目录路径

返回值说明：

• 结果为 true 删除目录成功
• 若待删除的目录 path 下还存在任何文件或子目录，将返回『不允许删除』的错误

举例说明：

	String path = "/dir1/dir2/";
    // 删除目录
    Response result = manager.rmDir(path); 

---

获取目录文件列表

方法原型：

	public Response readDirIter(String path,Map<String, String> params);

参数说明：

• path 目录路径
• params 可选参数

举例说明：

	String path = "/dir1/";
    // 获取目录中文件列表
    Response response = manager.readDirIter(path,null);
    System.out.println(response.body().string());

---

上传文件

方法原型：

public Response writeFile(String filePath, byte[] data, Map<String, String> params)
public Response writeFile(String filePath, File file, Map<String, String> params)
public Response writeFile(String filePath, InputStream inputStream, Map<String, String> params)

参数说明：

• filePath 保存到又拍云存储的文件路径，以/开始
• 第二个参数 接受 InputStream 、 File 和 byte[] 三种类型的数据
• params 上传额外可选参数，详见 api 文档。

返回值说明：

• response.isSuccessful() 结果为 true 上传文件成功

举例说明：

    // 例1：上传纯文本内容，自动创建父级目录
    String str = "Hello RestManager";
    Map<String, String> params = new HashMap<String, String>();
        // 设置待上传文件的 Content-MD5 值
        // 如果又拍云服务端收到的文件MD5值与用户设置的不一致，将回报 406 NotAcceptable 错误
    params.put(PARAMS.CONTENT_MD5.getValue(), UpYunUtils.md5(file, 1024));

        // 设置待上传文件的"访问密钥"
        // 注意：
        // 仅支持图片空！，设置密钥后，无法根据原文件URL直接访问，需带URL后面加上（缩略图间隔标志符+密钥）进行访问
        // 举例：
        // 如果缩略图间隔标志符为"!"，密钥为"bac"，上传文件路径为"/folder/test.jpg"，
        // 那么该图片的对外访问地址为：http://空间域名 /folder/test.jpg!bac
    params.put(PARAMS.CONTENT_SECRET.getValue(), "bac");
    Response result = manager.writeFile("/path/to/file", str, params);
    

注： 若空间内指定目录已存在相同文件，则会被覆盖，且不可逆。若要避免此情况，可以先通过获取文件信息来判断是否已经存在相同文件

---

获取文件信息

方法原型：

public Response getFileInfo(String filePath)

参数说明：

• filePath 又拍云中文件的路径

返回值说明：

• response.headers 信息：

• x-upyun-file-type 文件类型
• x-upyun-file-size 文件大小
• x-upyun-file-date 创建日期
• Content-Md5 文件的 MD5 值

举例说明：

	String filePath = "/path/to/file";
	System.out.println(filePath + " 的文件信息：" + restManager.getFileInfo(filePath).headers());

---

获取使用量信息

方法原型：

	public Resoponse getBucketUsage();

举例说明：

	Response response = restManager.getBucketUsage();
	System.out.println("空间总使用量：" + response.body().string() + "B");    	

返回值说明：

• 返回值单位为 Byte

---

下载文件

方法原型：

	public Response readFile(String filePath)；

参数说明：

• filePath 文件在又拍云存储中的路径

返回值说明：

• response.body() 包含文件流信息

举例说明：

    // 直接打印文本内容
    String remoteFilePath = "/path/to/file";
    System.out.println(filePath + " 的文件内容:" + response.body().string());

---

删除文件

方法原型：

	public Response deleteFile(String filePath,Map<String, String> params);

参数说明：

• filePath 文件在又拍云的路径
• params 可选参数 可为 null

返回值说明：

• response.isSuccessful() 结果为 true 删除文件成功

举例说明：

	Response response = restManager.deleteFile(filePath, null);
	System.out.println(filePath + " 删除" + isSuccess(response));

移动文件

方法原型：

	public Response moveFile(String path, String sourcePath, Map<String, String> params);

参数说明：

• path 目标路径
• sourcePath 源文件路径

返回值说明：

• 返回 Response

复制文件

方法原型：

	public Response copyFile(String path, String sourcePath, Map<String, String> params);

参数说明：

• path 目标路径
• sourcePath 源文件路径

返回值说明：

• 返回 Response

---

串行式断点续传

初始化 SerialUploader

	SerialUploader resume = new SerialUploader("空间名称", "操作员名称", "操作员密码")

设置上传进度监听

	 resume.setOnProgressListener(new BaseUploader.OnProgressListener()

设置 MD5 校验

	resume.setCheckMD5(true);

开始上传

	public boolean upload(String filePath, String uploadPath,Map<String, String> params)	

暂停

	public boolean pause()	

继续

	public boolean resume()	

---

并行式断点续传

初始化 ParallelUploader

	ParallelUploader paralleUploader = new ParallelUploader("空间名称", "操作员名称", "操作员密码")

设置上传进度监听

	 paralleUploader.setOnProgressListener(new ResumeUploader.OnProgressListener()

设置 MD5 校验

	paralleUploader.setCheckMD5(true);

设置 并行数 校验

	paralleUploader.setParallel(4);

开始上传

	public boolean upload(String filePath, String uploadPath,Map<String, String> params)	

暂停

	public boolean pause()	

继续

	public boolean resume()	

参数说明：

• filePath 待上传文件路径
• uploadPath 上传至空间目录
• params 通用可选上传参数见文档 可为null

详细示例： 见 ResumeUploadDemo

---

表单上传接口

初始化 FormUploader

 	public FormUploader(String bucketName, String userName, String password) 

参数说明：

• bucketName 空间名
• userName 操作员
• password 密码

可选属性：

• 手动设置超时时间：默认为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<String, Object> params, File file) 
	public Result upload(Map<String, Object> params, byte[] datas) 

参数说明：

• params 参数键值对
• file 上传文件
• datas 上传数组

参数键值对中 Params.SAVE_KEY 为必选参数，其他可选参数见 Params 或者官网 API 文档。

返回说明:

• Result.Succeed 是否成功
• Result.code 返回http消息码
• Result.msg 返回消息

举例说明：

表单上传示例可见 FormUploadDemo 。

###表单上传作图

上传同步作图

     private static void testSync() {
        //初始化uploader
        FormUploader uploader = new FormUploader(BUCKET_NAME, APIKEY, null);

        //初始化参数组 Map
        final Map<String, Object> paramsMap = new HashMap<String, Object>();

        //添加 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<String, Object> paramsMap = new HashMap<String, Object>();

        //添加 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<String, Object> params) throws IOException 

参数说明：

• params 参数键值对

详细参数可见 MediaHandler 或者官网 API 文档。

返回说明:

• Result.Succeed 是否成功
• Result.code 返回http消息码
• Result.msg 返回消息

举例说明：

示例可见 testMediaProcess 。

查询处理进度

方法原型：

	 public Result getStatus(Map<String, Object> params) throws IOException 

参数说明：

• params 参数键值对 包括 bucket_name 和 task_ids

返回说明:

同上

举例说明：

示例可见 testMediaStatus 。

查询处理结果

方法原型：

	 public Result getResult(Map<String, Object> params) throws IOException

参数说明：

同上

返回说明:

同上

举例说明：

示例可见 testMediaResult 。

压缩解压缩

初始化 CompressHandler

	MediaHandler handle = new MediaHandler(BUCKET_NAME, OPERATOR_NAME, OPERATOR_PWD);

参数说明：

• BUCKET_NAME 空间名
• OPERATOR_NAME 操作员名称
• OPERATOR_PWD 操作员密码

发起异步处理请求

	 public Result process(Map<String, Object> params) throws IOException 

参数说明：

• params 参数键值对

详细参数可见 CompressHandler 或者官网 API 文档。

详细示例见 CompressDemo

异步文件拉取

初始化 CompressHandler

	MediaHandler handle = new MediaHandler(BUCKET_NAME, OPERATOR_NAME, OPERATOR_PWD);

参数说明：同上

发起异步处理请求

	 public Result process(Map<String, Object> params) throws IOException 

参数说明：

• params 参数键值对

详细参数可见 PullingHandler 或者官网 API 文档。

详细示例见 PullingDemo

文档转换

初始化 CompressHandler

	ConvertHandler handle = new ConvertHandler(BUCKET_NAME, OPERATOR_NAME, OPERATOR_PWD);

参数说明：同上

发起异步处理请求

	 public Result process(Map<String, Object> params) throws IOException 

参数说明：

• params 参数键值对

详细参数可见 ConvertHandler 或者官网 API 文档。

详细示例见 JigsawDemo

图片拼接

初始化 JigsawHandler

	JigsawHandler handle = new JigsawHandler(BUCKET_NAME, OPERATOR_NAME, OPERATOR_PWD);

参数说明：同上

发起异步处理请求

	 public Result process(Map<String, Object> params) throws IOException 

参数说明：

• params 参数键值对

详细参数可见 JigsawHandler 或者官网 API 文档。

详细示例见 JigsawDemo

##错误说明

请参照 API 错误码表