UPYUN Java SDK
Java
Clone or download
Latest commit 57a4b31 Jun 28, 2018

README.md

UPYUN Java SDK

Build Status

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

Maven 安装

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

更新说明

使用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<FolderItem> readDir(String path);

UpYun.FolderItem 包含属性:

  • name 文件名
  • type 文件类型
  • size 文件大小
  • date 文件创建日期

以上属性作用域皆为 public,可直接调用

参数说明:

  • path 目录路径

返回值说明:

  • path 目录没有内容时,返回null
  • path 目录不存在时,则将返『不存在目录』的错误

举例说明:

	String path = "/dir1/";
    // 获取目录中文件列表
    List<UpYun.FolderItem> 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 保存到又拍云存储的文件路径,以/开始
  • 第二个参数 接受 StringFilebyte[] 三种类型的数据
  • 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<String, String> getFileInfo(String filePath);

参数说明:

  • filePath 又拍云中文件的路径

返回值说明:

  • filePath 所指定文件不存在,则直接返回 null
  • Map 包含3个Key:
  • type 文件类型
  • size 文件大小
  • date 创建日期

举例说明:

	String filePath = "/path/to/file";
    // 获取文件信息
    Map<String, String> info = upyun.getFileInfo(filePath);
    String type = info.get("type"); 
    String size = info.get("size"); 
    String date = info.get("date");

获取使用量信息

方法原型:

	public long getBucketUsage();

举例说明:

    // 例1:获取整个空间的使用量情况
    long usage = upyun.getBucketUsage();

返回值说明:

  • 返回值单位为 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);

断点续传

初始化 ResumeUploader

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

设置上传进度监听

	 resume.setOnProgressListener(new ResumeUploader.OnProgressListener()

设置 MD5 校验

	resume.setCheckMD5(true);

开始上传

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

参数说明:

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

详细示例:ResumeUploadDemo

图片处理接口

方法原型:

	public boolean writeFile(String filePath, File file, boolean 	auto, Map<String, String> params);
	public boolean writeFile(String filePath, byte[] datas, boolean 	auto, Map<String, String> params);
	public boolean writeFile(String filePath, String datas, boolean 	auto, Map<String, String> params);

参数说明:

  • filePath 保存到又拍云存储的路径
  • 第二个参数 接受 StringFilebyte[] 三种类型的图片数据内容
  • auto (可选):自动创建父级目录(只支持自动创建10级以内的父级目录)
  • params 自定义图片处理参数的组合,详情请看params参数说明

返回值说明:

  • 结果为 true 图片上传并处理成功

图片处理包括『制作图片缩略图』,『图片裁剪』,『图片旋转』。只需要选则不同的 PARAMS 参数就可以分别完成这些操作,下面分别举例说明。


制作图片缩略图

举例说明:

    Map<String, String> params = new HashMap<String, String>();
    
    // 设置缩略图类型
    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<String, String> params = new HashMap<String, String>();
    
    // 设置图片裁剪,参数格式: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<String, String> params = new HashMap<String, String>();
    
    // 设置图片旋转
    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

 	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_nametask_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

##错误说明

请参照 API 错误码表