upyun-sdk-spring-boot-starter/README.md

19 KiB
Raw Permalink Blame History

upyun-sdk-spring-boot-starter

1. 简介

本项目是基于又拍云 Java SDK 封装的 SpringBoot starter以适应 SpringBoot 项目的开发风格,便于在 SpringBoot 项目中使用。

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

2. 使用说明

本项目基于又拍云官方 java-sdk 做了简单封装,自动装配了主要实例,无需手动实例化。

已自动装配的实例:

  • RestManager
  • SerialUploader
  • ParallelUploader
  • FormUploader
  • MediaHandler
  • ConvertHandler
  • JigsawHandler

SDK 中提供的所有方法都在以上实例中,可以参考下面官方 SDK 文档使用(注意:文档中使用 new 的实例已经实现自动装配,无需手动实例化)。

// 正确姿势
@Autowired
private RestManager restManager;

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

3. 快速开始

3.1 添加依赖

<dependency>
  <groupId>cn.surcode</groupId>
  <artifactId>upyun-sdk-spring-boot-starter</artifactId>
  <version>v1.0.0</version>
</dependency>

3.2 配置属性

upyun:
  bucket: # 空间名称(必填)
  operator: # 操作员(必填)
  password: # 密码(必填)
  timeout: # 超时时间默认为30s
  apiDomain: # 最优接入点可选值auto 自动选择默认值、telecom 电信接入点、cnc 联通网通接入点、ctt 移动铁通接入点

又拍云存储sdk api请参考文档使用

目录

云存储基础接口

初始化 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 Filebyte[] 三种类型的数据
  • params 上传额外可选参数,详见 api 文档
  • 官方 api 文档中params 必传参数 Date 使用 GMT 字符串,这里可以使用 UpYunUtils.getGMTDate() 方法

返回值说明:

  • 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_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

文档转换

初始化 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 错误码表