文档

使用Android SDK上传文件

文件上传是指将媒体文件(本地文件或网络文件)从客户端上传至点播存储。在Android端上,文件上传通过上传实例(VODUploadClient)完成。视频上传成功后会返回videoId作为视频ID,用户需要通过拿到videoId自行获取播放地址进行播放。本文介绍如何使用Android端上传SDK完成媒体文件上传。

前提条件

您已集成Android端上传SDK。详情请参见集成Android端上传SDK

上传流程

客户端上传SDK封装了OSS上传逻辑。在客户端上传媒体文件时,会直接将文件上传到点播存储(基于OSS),不会再经服务端进行中转,故客户端上传必须进行鉴权,也就是需要您在应用服务器上部署授权服务以获取上传地址和凭证。目前客户端上传SDK支持两种授权方式,两种方式差异对比请参见凭证方式与STS方式对比,推荐使用凭证方式。

上传地址和凭证方式上传流程详解

以集成点播服务端SDK获取上传地址和凭证为例,完整的上传流程如下图所示:客户端SDK上传凭证上传流程

  1. 用户在上传应用服务器上部署授权服务(如集成点播服务端SDK)用于获取上传地址和凭证。

  2. 客户端向上传应用服务器发起请求获取上传地址和凭证。

  3. 上传应用服务器向视频点播服务发起请求获取上传地址和凭证。

  4. 点播服务返回上传地址和凭证。

    说明

    点播服务在下发上传地址和凭证时还会自动创建媒资信息,即媒体ID(MediaId),用于媒资生命周期管理或媒体处理。

    • 获取音视频上传地址和凭证返回的VideoId即媒体ID。

    • 获取图片上传地址和凭证返回的ImageId即媒体ID。

    • 获取辅助媒资上传地址和凭证返回的MediaId即媒体ID。

    • 请妥善保存媒体ID,作为媒资管理、音视频播放、媒体处理等的输入。

  5. 上传应用服务器向客户端下发上传地址和凭证。

    说明

    下发地址和凭证即可,无需Base64解码。

  6. 客户端使用上传地址和凭证初始化上传实例。

  7. 客户端构造上传参数发起上传请求。

  8. OSS服务返回上传结果。

    说明

    上传结果也可以通过提前配置回调接收上传相关事件来监听。

STS方式上传流程详解

如需使用STS临时授权方式(阿里云Security Token Service)访问点播服务,请为RAM用户创建角色并授予角色VOD相关权限。操作指引请参见使用STS临时授权方案上传视频

使用STS方式上传的完整的流程如下图所示:客户端STS方式上传流程

  1. 用户在上传应用服务器上部署授权服务(如集成阿里云STS SDK)用于获取STS临时Token。

  2. 客户端向上传应用服务器发起请求获取STS临时Token。

  3. 上传应用服务器向阿里云STS服务发起请求获取STS临时Token。

  4. 阿里云STS服务返回上传地址和凭证。

  5. 上传应用服务器向客户端下发STS临时Token。

  6. 客户端使用STS临时Token初始化上传实例。

  7. 客户端构造请求发起上传请求。

  8. OSS服务返回上传结果。

    说明

    上传结果也可以通过提前配置回调接收上传相关事件来监听。

上传文件

在Android端上传文件的基本操作步骤如下:

  1. 获取上传地址和凭证STS临时Token,用于上传授权。

  2. 使用上传凭证STS临时Token初始化上传实例。

  3. 设置回调,用于接收上传过程中关键节点的消息。

  4. 根据上传的文件类型(音视频或图片)构造上传参数。

  5. 开始上传。

说明

音视频和图片的上传参数略有差异。目前客户端不支持上传辅助媒资。

步骤一、获取上传授权

点播客户端上传SDK支持两种授权方式,分别是凭证方式和STS方式。关于两种方式的适用场景请参见凭证方式与STS方式对比

执行结果

用获取到的上传地址和凭证或STS临时Token作为入参初始化上传实例。

步骤二、初始化上传实例

请根据业务需求选择用上传地址和凭证方式STS方式初始化上传实例。

(推荐)方式一:上传地址和凭证方式初始化上传实例

1.声明上传实例(VODUploadClient)初始化回调。

uploader = new VODUploadClientImpl(getApplicationContext());

2.初始化上传实例(VODUploadClient)。

说明
  • 上传地址和凭证方式调用init方法初始化。

  • 在上传开始后触发的onUploadStarted回调中调用setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress)方法设置上传地址和凭证。

  • 音视频上传场景下,如果上传地址和凭证过期,会触发onUploadTokenExpired回调,需要调用resumeWithAuth(uploadAuth)方法,设置新的上传凭证继续上传。

展开查看代码

// create VODUploadClient
final VODUploadClient uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
VODUploadCallback callback = new VODUploadCallback(){
    @Override
    public void onUploadSucceed(UploadFileInfo info) {
        OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
    }

    @Override
    public void onUploadFailed(UploadFileInfo info, String code, String message) {
        OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
    }

    @Override
    public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
        OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
    }

    @Override
    public void onUploadTokenExpired() {
        OSSLog.logError("onExpired ------------- ");
        //重新刷新上传凭证:RefreshUploadVideo。
        uploadAuth = "此处需要设置重新刷新凭证之后的值";
        uploader.resumeWithAuth(uploadAuth);
    }

    @Override
    public void onUploadRetry(String code, String message) {
        OSSLog.logError("onUploadRetry ------------- ");
    }

    @Override
    public void onUploadRetryResume() {
        OSSLog.logError("onUploadRetryResume ------------- ");
    }

    @Override
    public void onUploadStarted(UploadFileInfo uploadFileInfo) {
        OSSLog.logError("onUploadStarted ------------- ");
        //uploadAuth及uploadAddress即为上传凭证和地址。
        uploader.setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress);
    }
};
//上传初始化
uploader.init(callback);

方式二:STS方式初始化上传实例

1.声明上传实例(VODUploadClient)初始化回调。

uploader = new VODUploadClientImpl(getApplicationContext());

2.初始化上传实例(VODUploadClient)。

说明
  • STS方式调用init(accessKeyId, accessKeySecret, secretToken, expireTime, callback)方法初始化,

  • 初始化参数secretToken是请求获取的临时STS凭证。

  • 当STS临时凭证过期时,触发OnUploadTokenExpired回调,需要调用resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime)方法,设置新的STS继续上传。

展开查看代码

// create VODUploadClient object
uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
// setup callback
VODUploadCallback callback = new VODUploadCallback() {
            public void onUploadSucceed(UploadFileInfo info) {
                OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
            }
            public void onUploadFailed(UploadFileInfo info, String code, String message) {
                OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
            }
            public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
                OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
                    }
                }
            }
            public void onUploadTokenExpired() {
                OSSLog.logError("onExpired ------------- ");
                    //重新获取STS之后调用resumeWithToken
                    uploader.resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime);
            }
            public void onUploadRetry(String code, String message) {
                OSSLog.logError("onUploadRetry ------------- ");
            }
            public void onUploadRetryResume() {
                OSSLog.logError("onUploadRetryResume ------------- ");
            }
            public void onUploadStarted(UploadFileInfo uploadFileInfo) {
                OSSLog.logError("onUploadStarted ------------- ");
            }
        };
//初始化,临时账号过期时,在onUploadTokenExpired事件中,用resumeWithToken更新临时账号,上传默认支持断点续传
uploader.init(accessKeyId, accessKeySecret, secretToken, expireTime, callback);

步骤三、设置上传状态回调类

设置VODUploadCallback对象,该对象是上传状态的回调类。需要设置下列回调方法:

展开查看代码

/**
 上传完成回调
 @param info 上传文件信息
 */
void onUploadSucceed(UploadFileInfo info);
/**
 上传失败回调
 @param info 上传文件信息
 @param code 错误码
 @param message 错误描述
 */
 void onUploadFailed(UploadFileInfo info, String code, String message);
/**
 上传进度回调
 @param fileInfo 上传文件信息
 @param uploadedSize 已上传大小
 @param totalSize 总大小
 */
 void onUploadProgress(UploadFileInfo fileInfo, long uploadedSize, long totalSize);
/**
 上传地址和凭证过期回调
 上传地址和凭证方式上传需要调用resumeWithAuth方法继续上传
 STS方式上传需要调用resumeWithToken方法继续上传
 */
 void onUploadTokenExpired();
/**
 上传开始重试回调
 */
 void onUploadRetry(String code, String message);
/**
 上传结束重试,继续上传回调
 */
 void onUploadRetryResume ();
/**
 开始上传回调
 上传地址和凭证方式上传需要调用setUploadAuthAndAddress:uploadAuth:uploadAddress:方法设置上传地址和凭证
 @param fileInfo 上传文件信息
 */
  void onUploadStarted(UploadFileInfo fileInfo);

步骤四、构造上传请求函数

音视频文件参数

构造添加音视频文件到上传列表的上传请求函数。

String filePath = "文件地址";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("标题" + index);
vodInfo.setDesc("描述." + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);

图片文件参数

构造添加图片文件到上传列表的上传请求函数。

String filePath = “图片文件地址”;
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle(“标题” + index);
vodInfo.setDesc(“描述.” + index);
vodInfo.cateId (19);
vodInfo.tags(“sports”);
uploader.addFile(filePath,vodInfo);

vodInfo说明

//标题
String title;
//标签
List tags;
//描述
String desc;
//分类
idInteger cateId;
//封面url(完整的URL https://)
String coverUrl;
说明

添加文件后,SDK会将待上传文件封装为UploadFileInfo对象,具体结构如下:

//文件本地路径
String filePath;
//endpoint
String endpoint;
//bucket
String bucket;
//object
String object;
//VodInfo
VodInfo vodInfo;

步骤五、开始上传

  1. 调用start()方法开始上传。

    void start();

    该方法调用后,会触发onUploadStarted回调。如果通过上传地址和凭证方式上传,需要在该回调方法中设置上传地址和凭证。示例代码如下:

    void setUploadAuthAndAddress(UploadFileInfo uploadFileInfo, String uploadAuth, String uploadAddress)

  2. 文件开始上传后,onUploadProgress回调开始同步上传进度。

  3. 文件上传成功后,onUploadSucceed回调会返回上传结果。回调包含上传结果的videoIdimageUrl属性。

执行结果

  • 视频上传成功后会返回videoId作为视频ID,拿到videoId之后需要获取播放地址进行播放。更多信息,请参见通过播放凭证播放

  • 图片上传完成后会返回imageUrl,开启URL鉴权后imageUrl会有过期时间。更多信息,请参见URL鉴权

高级功能

队列管理

上传实例(VODUploadClient)支持添加多个文件顺序上传,并提供了以下方法管理上传队列:

说明

尽管VODUploadClient支持多文件上传,如果使用上传凭证和上传地址方式上传,每个文件还是需要单独设置。基于多文件上传代码复杂度的考虑,建议只添加单文件上传。

  • 从队列中删除上传文件。如果待删除的文件正在上传中,则取消上传并自动上传下一个文件。

    void deleteFile(int index)
  • 清空上传队列。如果有文件在上传,则取消上传。

    void clearFiles()
  • 获取上传文件队列。

    List<UploadFileInfo> listFiles()
  • 将文件标记为取消,文件仍保留在上传列表中。如果待取消的文件正在上传中,则取消上传并自动上传下一个文件。

    cancelFile(int index)
  • 恢复已取消上传的文件,并自动开始上传。

    resumeFile(int index)

上传控制

上传实例(VODUploadClient)支持以下上传控制方法:

  • 停止上传。如果有文件正在上传中,则取消上传。

    void stop();
    说明

    停止上传后如需恢复上传,请调用resumeFile恢复待上传文件,或者清空队列后重新添加文件上传。

  • 暂停上传。

    void pause();
  • 恢复上传。

    void resume();

回调处理

上传实例(VODUploadClient)支持以下回调:

  • 上传失败

    上传失败时,会触发onUploadFailed回调。在该回调方法中,可以通过codemessage查看具体原因,并在页面上提示。更多错误码信息,请参见错误码表OSS错误码

  • 上传地址和凭证过期

    上传凭证过期,会触发onUploadTokenExpired回调。在该回调方法中,可以向AppServer重新请求新的上传凭证,并调用以下方法继续上传。

    说明

    需要在回调中设置刷新后的上传凭证。

  • 上传超时

    上传超时,会触发uploadRetry回调并自动重试。在该回调方法中,可以在页面上给予提示或者调用cancel方法停止上传。此外,可以设置maxRetryCount属性,指定最大重试次数。超时重试可以继续上传时,会触发uploadRetryResume回调并恢复上传。

超时处理

上传实例(VODUploadClient)支持设置最大超时次数:

/**
配置最大超时重试次数,默认值INT_MAX,超时时间
 */
void setVodHttpClientConfig(VodHttpClientConfig var);

分片上传设置

上传实例(VODUploadClient)支持设置文件大小来控制是否需要启用分片上传。如果文件超过partSize设置的大小就会采用分片上传。

/**
 分片大小,默认值1024 * 1024。单位字节。如果文件超过partSize设置的大小就会采用分片上传。
*/
void setPartSize(long partSize);

指定存储地址

上传实例(VODUploadClient)支持指定上传文件的存储地址。不指定时文件上传到默认存储地址。存储地址需要提前启用或配置。更多信息请参见存储说明

/**
* 指定文件的存储地址。登录点播控制台,选择配置管理 > 媒资管理配置 > 存储管理查看存储地址。
*/
void setStorageLocation(String storageLocation);

设置转码

上传实例(VODUploadClient)支持通过指定转码模板组ID设置转码。

/**
* 设置转码模板组Id。登录点播控制台,选择配置管理 > 媒体处理配置 > 转码模板组,查看转码模板组ID。
*/
void setTemplateGroupId(String templateGroupId);
重要

客户端上传SDK不支持通过工作流方式设置转码。

断点续传

客户端上传SDK支持断点续传。用户仅需保证以下方法的值为YES。

/**
 * 是否记录上传进度(断点续传),默认值YES。仅当参数值设为YES时上传SDK内部自动实现断点续传。如果设置为NO,断点续传功能为关闭状态。
 */
void setRecordUploadProgressEnabled(boolean var1);

设置点播服务地域

上传实例(VODUploadClient)支持设置存储地域。

/**
 vod region,默认值"cn-shanghai"。
 */
void setRegion(String var);

  • 本页导读 (1)
文档反馈