CDN加速

JAVA 上传SDK

更新时间:2021-04-27 15:20:20

目录

一、简介

为便于JAVA开发者在自己的程序中能便捷的使用CloudV文件上传接口,我们为客户提供java-sdk-upload工具包,工具包可以将客户本地的视频自动上传到CloudV平台上,并返回videoId。

二、特性

  1. 支持普通上传、分片上传
  2. 分片上传支持多个片并发上传
  3. 文件大小小于50M,SDK自动使用普通上传
  4. 文件大小大于等于50M,SDK自动使用分片上传
  5. 文件上传后会自动比较hash值,确保文件完整无缺失
  6. 分片文件上传过程中如果失败,会自动重试,重新上传失败的片,默认重试3次

三、使用前提

  1. 仅支持java平台使用,要求jdk 1.6及以上版本。建议jdk 1.8版本。
  2. 确认已成为CloudV用户,并获得用户ID(userId)和秘钥(secretKey)

四、使用说明

4.1、将SDK引入java工程

  1. 下载并解压 cnc-java-sdk-cloudv-upload-xxx-with-lib.zip
  2. 引入cnc-java-sdk-cloudv-upload-xxx.jar到java工程
  3. 引入lib文件夹内的所有第三方依赖jar包到java工程
    注:xxx为SDK的版本号

4.2、视频上传

4.2.1、调用的类及方法

com.cnc.cloudv.sdk.upload.CloudvUploadHandler
方法 public String upload(String uploadFilePath, String userId, String secretKey, UploadObserver uploadObserver, UploadFileParam uploadFileParam) throws CloudvException, HttpClientException

4.2.2、输入参数

参数名 类型 是否必填 描述
uploadfilePath string 必填 要上传文件的完整路径
userId string 必填 用户的唯一标识,从CloudV网站上获取。
secretKey string 必填 用于计算校验字符串的密钥,从CloudV网站上获取。
uploadObserver UploadObserver 非必填 实现UploadObserver接口的对象,用于接收上传开始、上传成功、上传失败、上传进度的回调通知。 如需要自定义,详看5.2、上传进度通知
uploadFileParam UploadFileParam 非必填 可设置各种参数,具体如下描述

uploadFileParam格式说明

参数名 类型 是否必填 描述
categoryNameBeanList list 非必填 视频分类名称。
transCodeCombineName string 非必填 转码组合模板名。 如果设值,上传视频成功后会自动进行转码。
waterMarkName string 非必填 水印名称。transCodeCombineName有填时才有效。如果transCodeCombineName有值,而waterMarkName没值,则代表转码不加水印。
domain string 非必填 发布域名。填写域名名称,不填或者填写的域名不存在则会使用点播视频的默认域名。

categoryNameBeanList格式说明

参数名 类型 是否必填 描述
parentName string 必填 第一级分类名称
childName string 必填 第二级分类名称

4.2.3、返回结果

类型 描述
string 视频ID,视频信息唯一标识

4.2.4、示例

public static void main(String[] args) {
    try {
        CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
        String filePath = "F:\\test.mp4";
        String userId = "xxxxxx";
        String secretKey = "xxxxxxxxxxxxxxxxxxxx";
        CategoryNameBean categoryNameBean = new CategoryNameBean();
        categoryNameBean.setParentName("第一级分类名称");
        categoryNameBean.setChildName("第二级分类名称");
        List<CategoryNameBean> categoryNameBeanList = new ArrayList<CategoryNameBean>();
        categoryNameBeanList.add(categoryNameBean);
        String transCodeCombineName = "转码模板名称";
        String waterMarkName = "水印名称";
        String domain = "域名名称";

        UploadFileParam uploadFileParam = new UploadFileParam();
        uploadFileParam.setCategoryNameBeanList(categoryNameBeanList);
        uploadFileParam.setTransCodeCombineName(transCodeCombineName);
        uploadFileParam.setWaterMarkName(waterMarkName);
        uploadFileParam.setDomain(domain);
        String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey, null, uploadFileParam);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

五、高级配置

5.1、上传参数配置

5.1.1、描述

一般情况下,默认配置即可满足上传的速度与稳定性。在一些特殊情况,如果上传速度或稳定性无法满足,可调整上传参数配置。上传参数配置设置后全局生效。

5.1.2、配置项

名称 描述 默认值 设值示例
分片上传-块大小 分片上传块的大小。取值范围:4M-32M,且为4的倍数。 4MB BaseBlockUtil.BLOCK_SIZE = 32 * BaseBlockUtil.MB;
分片上传-片大小 分片上传片的大小。取值范围:4M-32M,且为4的倍数。不能大于设置的块大小。适当增大片大小可能会提高上传速度。 4MB BaseBlockUtil.CHUNK_SIZE = 4 * BaseBlockUtil.MB;
分片上传-并发数 配置范围为1-10 如果配置为5,表示可并发上传5个分片 5 BaseBlockUtil.THREAD_NUN = 5;
分片上传-文件缓冲区大小 读取要上传的文件的缓冲区大小。适当增大设置可能会提高上传速度,但内存使用将会变大。设值需为4的倍数。 4KB BaseBlockUtil.FILE_BUFFER_SIZE = 1024 * BaseBlockUtil.KB;
分片上传-上传失败自动重试次数 影响当块、片上传失败后,自动重传重试的次数。 3 BaseBlockUtil.TRIED_TIMES = 5;

5.1.3、示例

public static void main(String[] args) {
    try {
        //设置块大小
        BaseBlockUtil.BLOCK_SIZE = 32 * BaseBlockUtil.MB;
        //设置片大小
        BaseBlockUtil.CHUNK_SIZE = 4 * BaseBlockUtil.MB;
        //设置片并发数
        BaseBlockUtil.THREAD_NUN = 5;
        //设置文件缓冲区大小
        BaseBlockUtil.FILE_BUFFER_SIZE = 2 * BaseBlockUtil.MB;
        //设置出错重试次数
        BaseBlockUtil.TRIED_TIMES = 5;
        CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
        String filePath = "D:\\test.mp4";
        String userId = "xxxxxx";
        String secretKey = "xxxxxxxxxxxxxxxxxxxx";
        String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey, null);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

5.2、上传进度通知

5.2.1、描述

如果使用者有获取上传进度(开始上传、上传进度、上传成功、上传失败)的需要,可以自定义实现消费上传进度通知。

5.2.2、使用方法

  1. 新建一个类实现com.cnc.cloudv.sdk.upload.observer.UploadObserver接口
  2. 实现接口中的4个方法
  3. 调用方法增加入参uploadObserver
public interface UploadObserver {
    /**
     * 在开始上传之前调用,回传id
     * @param id
     * @param filePath
     */
    void onBegin(String id, String filePath);

    /**
     * 上传成功后调用
     * @param result
     */
    void onSuccess(UploadResult result);

    /**
     * 上传发生异常时调用
     * @param ex
     */
    void onFail(Exception ex);

    /**
     * 每次上传分片成功后回调
     *
     * @param uploaded 已上传的字节数
     * @param total    总字节数
     */
    void onProcess(long uploaded, long total);
}

5.2.3、示例

public class CustomUploadObserver implements UploadObserver {
    private static final Logger LOGGER = LoggerFactory.getLogger(CustomUploadObserver.class);
    private String videoId;
    private String filePath;

    @Override
    public void onBegin(String videoId, String filePath) {
        this.videoId = videoId;
        this.filePath = filePath;
        LOGGER.info("videoId:{}, filePath:{}, 开始上传", videoId, filePath);
    }

    @Override
    public void onSuccess(UploadResult result) {
        LOGGER.info("videoId:{}, filePath:{}, 上传成功", videoId, filePath);
    }

    @Override
    public void onFail(Exception ex) {
        String message = "videoId:" + videoId + "filePath:" + filePath + ",上传出错";
        LOGGER.error("message:{}, error:", message, ex);
        throw new RuntimeException(message, ex);
    }

    @Override
    public void onProcess(long uploaded, long total) {
        LOGGER.info("videoId:{},filePath:{}, 上传进度:{},", videoId, filePath, uploaded * 100 / total + "%");
    }
}

调用方法:

public static void main(String[] args) {
        try {
            CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
            String filePath = "D:\\test.mp4";
            String userId = "xxxxxx";
            String secretKey = "xxxxxxxxxxxxxxxxxxxx";
            CustomUploadObserver uploadObserver = new CustomUploadObserver();
            String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey,  uploadObserver);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }