文件上传是指将媒体文件(本地文件或网络文件)从客户端上传至点播存储。在iOS端上,文件上传通过上传实例(VODUploadClient)完成。本文介绍如何使用iOS端上传SDK完成媒体上传。
上传流程
客户端上传SDK封装了OSS上传逻辑。在客户端上传媒体文件时,会直接将文件上传到点播存储(基于OSS),不会再经服务端进行中转,故客户端上传必须进行鉴权,也就是需要您在应用服务器上部署授权服务以获取上传地址和凭证。目前客户端上传SDK支持两种授权方式,两种方式差异对比请参见凭证方式与STS方式对比,推荐使用凭证方式。
上传地址和凭证方式上传流程详解
以集成点播服务端SDK获取上传地址和凭证为例,完整的上传流程如下图所示:
用户在上传应用服务器上部署授权服务(如集成点播服务端SDK)用于获取上传地址和凭证。
客户端向上传应用服务器发起请求获取上传地址和凭证。
上传应用服务器向视频点播服务发起请求获取上传地址和凭证。
点播服务返回上传地址和凭证。
说明 点播服务在下发上传地址和凭证时还会自动创建媒资信息,即媒体ID(MediaId),用于媒资生命周期管理或媒体处理。
获取音视频上传地址和凭证返回的VideoId
即媒体ID。
获取图片上传地址和凭证返回的ImageId
即媒体ID。
获取辅助媒资上传地址和凭证返回的MediaId
即媒体ID。
请妥善保存媒体ID,作为媒资管理、音视频播放、媒体处理等的输入。
上传应用服务器向客户端下发上传地址和凭证。
客户端使用上传地址和凭证初始化上传实例。
客户端构造上传参数发起上传请求。
OSS服务返回上传结果。
说明 上传结果也可以通过提前配置回调接收上传相关事件来监听。
STS方式上传流程详解
如需使用STS临时授权方式(阿里云Security Token Service)访问点播服务,请为RAM用户创建角色并授予角色VOD相关权限。操作指引请参见使用STS临时授权方案上传视频。
使用STS方式上传的完整的流程如下图所示:
用户在上传应用服务器上部署授权服务(如集成阿里云STS SDK)用于获取STS临时Token。
客户端向上传应用服务器发起请求获取STS临时Token。
上传应用服务器向阿里云STS服务发起请求获取STS临时Token。
阿里云STS服务返回上传地址和凭证。
上传应用服务器向客户端下发STS临时Token。
客户端使用STS临时Token初始化上传实例。
客户端构造请求发起上传请求。
OSS服务返回上传结果。
说明 上传结果也可以通过提前配置回调接收上传相关事件来监听。
上传文件
在iOS端上传文件的基本操作步骤如下:
获取上传地址和凭证或STS临时Token,用于上传授权。
iOS上传SDK支持以下两种上传授权方式,推荐使用凭证方式:
执行结果
使用获取到的上传地址和凭证或STS临时Token作为入参初始化上传实例。
使用上传凭证或STS临时Token初始化上传实例。
初始化上传实例分为声明初始化回调和初始化上传实例两步。
声明VODUploadClient
属性,不能是局部变量。
初始化上传实例。请根据业务需求选择用上传地址和凭证方式或STS方式初始化上传实例。
(推荐)上传地址和凭证方式
展开查看代码
//创建VODUploadClient对象
self.uploader = [VODUploadClient new];
//weakself
__weak typeof(self) weakSelf = self;
//setup callback
OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
NSLog(@"upload finished callback videoid:%@, imageurl:%@", result.videoId, result.imageUrl);
};
OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
NSLog(@"upload failed callback code = %@, error message = %@", code, message);
};
OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
NSLog(@"upload progress callback uploadedSize : %li, totalSize : %li", uploadedSize, totalSize);
};
OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
NSLog(@"upload token expired callback.");
//token过期,设置新的上传凭证,继续上传
[weakSelf.uploader resumeWithAuth:`new upload auth`];
};
OnUploadRertyListener RetryCallbackFunc = ^{
NSLog(@"upload retry begin callback.");
};
OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
NSLog(@"upload retry end callback.");
};
OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
NSLog(@"upload upload started callback.");
//设置上传地址和上传凭证
[weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:`upload auth` uploadAddress:`upload address`];
};
VODUploadListener *listener = [[VODUploadListener alloc] init];
listener.finish = FinishCallbackFunc;
listener.failure = FailedCallbackFunc;
listener.progress = ProgressCallbackFunc;
listener.expire = TokenExpiredCallbackFunc;
listener.retry = RetryCallbackFunc;
listener.retryResume = RetryResumeCallbackFunc;
listener.started = UploadStartedCallbackFunc;
//init with upload address and upload auth
[self.uploader init:listener];
STS方式初始化上传实例
说明 STS方式调用init
方法初始化,通过接口setKeyId:accessKeySecret:secretToken:expireTime:listener:
传入临时STS凭证。
当token过期时,触发OnUploadTokenExpiredListener
回调,需要调用resumeWithToken: accessKeySecret: secretToken: expireTime
方法,设置新的STS继续上传。
展开查看代码
//创建VODUploadClient对象
self.uploader = [VODUploadClient new];
//weakself
__weak typeof(self) weakSelf = self;
//setup callback
OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
NSLog(@"upload finished callback videoid:%@, imageurl:%@", result.videoId, result.imageUrl);
};
OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
NSLog(@"upload failed callback code = %@, error message = %@", code, message);
};
OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
NSLog(@"upload progress callback uploadedSize : %li, totalSize : %li", uploadedSize, totalSize);
};
OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
NSLog(@"upload token expired callback.");
//token过期,设置新的STS,继续上传
[weakSelf.uploader resumeWithToken:`STS Key Id` accessKeySecret:`STS Key Secret` secretToken:`STS Secret Token` expireTime:`STS Expire Time`];
};
OnUploadRertyListener RetryCallbackFunc = ^{
NSLog(@"upload retry begin callback.");
};
OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
NSLog(@"upload retry end callback.");
};
OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
NSLog(@"upload upload started callback.");
};
//init
VODUploadListener *listener = [[VODUploadListener alloc] init];
listener.finish = FinishCallbackFunc;
listener.failure = FailedCallbackFunc;
listener.progress = ProgressCallbackFunc;
listener.expire = TokenExpiredCallbackFunc;
listener.retry = RetryCallbackFunc;
listener.retryResume = RetryResumeCallbackFunc;
listener.started = UploadStartedCallbackFunc;
//set STS and listener
[self.uploader setKeyId:`STS Key Id` accessKeySecret:`STS Key Secret` secretToken:STS Secret Token` expireTime:`STS Expire Time` listener:listener];
设置回调,用于接收上传过程中关键节点的消息。
设置VODUploadListener
对象,该对象是上传状态的回调类,需要设置下列回调方法:
展开查看代码
/**
上传完成回调
@param fileInfo 上传文件信息
@param result 上传结果信息
*/
typedef void (^OnUploadFinishedListener) (UploadFileInfo* fileInfo, VodUploadResult* result);
/**
上传失败回调
@param fileInfo 上传文件信息
@param code 错误码
@param message 错误描述
*/
typedef void (^OnUploadFailedListener) (UploadFileInfo* fileInfo, NSString *code, NSString * message);
/**
上传进度回调
@param fileInfo 上传文件信息
@param uploadedSize 已上传大小
@param totalSize 总大小
*/
typedef void (^OnUploadProgressListener) (UploadFileInfo* fileInfo, long uploadedSize, long totalSize);
/**
token过期回调
上传地址和凭证方式上传需要调用resumeWithAuth:方法继续上传
STS方式上传需要调用resumeWithToken:accessKeySecret:secretToken:expireTime:方法继续上传
*/
typedef void (^OnUploadTokenExpiredListener) ();
/**
上传开始重试回调
*/
typedef void (^OnUploadRertyListener) ();
/**
上传结束重试,继续上传回调
*/
typedef void (^OnUploadRertyResumeListener) ();
/**
开始上传回调
上传地址和凭证方式上传需要调用setUploadAuthAndAddress:uploadAuth:uploadAddress:方法设置上传地址和凭证
@param fileInfo 上传文件信息
*/
typedef void (^OnUploadStartedListener) (UploadFileInfo* fileInfo);
根据上传的文件类型(音视频或图片)构造上传参数。
说明 音视频和图片的上传参数略有差异。目前客户端不支持上传辅助媒资。
音视频文件参数
构造添加音视频文件到上传列表的上传请求函数。
展开查看代码
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"视频源文件的名称" ofType:@"视频源文件的格式,例如mp4"];
VodInfo *vodInfo = [[VodInfo alloc] init];
vodInfo.title = @"视频上传后的名称";
vodInfo.desc =@"视频上传后的描述";
vodInfo.cateId = @(视频的分类ID);
vodInfo.tags = @"视频标签,例如sports";
[self.uploader addFile:filePath vodInfo:vodInfo];
VodInfo说明
展开查看代码
//标题
@property (nonatomic, copy) NSString* title;
//标签
@property (nonatomic, copy) NSString* tags;
//描述
@property (nonatomic, copy) NSString* desc;
//分类ID
@property (nonatomic, strong) NSNumber* cateId;
//封面url(完整的URL https://)
@property (nonatomic, copy) NSString* coverUrl;
添加文件后,SDK会将待上传文件封装为UploadFileInfo
对象,具体结构如下:
展开查看代码
//文件本地路径
@property (nonatomic, copy) NSString* filePath;
//endpoint
@property (nonatomic, copy) NSString* endpoint;
//bucket
@property (nonatomic, copy) NSString* bucket;
//object
@property (nonatomic, copy) NSString* object;
//VodInfo
@property (nonatomic, strong) VodInfo* vodInfo;
说明 如果需要对相册内的视频进行上传,那么通过选择器得到的选中视频的绝对路径,作为上传的filepath进行上传。
图片文件参数
展开查看代码
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"图片源文件的名称" ofType:@"图片源文件的格式,例如jpg"];
VodInfo *imageInfo = [[VodInfo alloc] init];
imageInfo.title = @"图片上传后的名称";
imageInfo.desc =@"图片上传后的描述";
imageInfo.cateId = @(图片的分类ID);
imageInfo.tags = @"图片标签,例如sports";
[self.uploader addFile:filePath vodInfo:imageInfo];
开始上传。
调用start
开始上传。
[self.uploader start];
该方法调用后,会触发OnUploadStartedListener
回调。如果通过上传地址和凭证方式上传,需要在该回调方法中设置上传地址和凭证。代码如下:
[weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:weakSelf.uploadAuth uploadAddress:weakSelf.uploadAddress];
文件开始上传后,OnUploadProgressListener
回调开始同步上传进度。
回调参数包括已上传文件大小uploadedSize
和总文件大小totalSize
。
文件上传成功后,OnUploadFinishedListener
回调会返回上传文件信息UploadFileInfo
和上传结果VodUploadResult
。
VodUploadResult
包含以下属性:
@property (nonatomic, copy) NSString* videoId;
@property (nonatomic, copy) NSString* imageUrl;
说明 videoId
只在STS方式上传视频成功后才有返回值,imageUrl
只在STS方式上传图片成功后才有返回值。如果使用上传地址和凭证方式上传,videoId
和imageUrl
不会返回,相应的值在请求上传地址和凭证时就可以获取到。
执行结果
队列管理
VODUploadClient
支持添加多个文件顺序上传,并且提供了以下方法管理上传队列:
说明 尽管VODUploadClient
支持多文件上传,如果使用上传凭证和地址方式上传,每个文件还是需要单独设置。基于多文件上传代码复杂度的考虑,建议只添加单文件上传。
从队列中删除上传文件,如果待删除的文件正在上传中,则取消上传并自动上传下一个文件。
- (BOOL)deleteFile:(int) index;
清空上传队列,如果有文件在上传,则取消上传。
- (BOOL)clearFiles;
获取上传文件队列。
- (NSMutableArray<UploadFileInfo *> *)listFiles;
将文件标记为取消,文件仍保留在上传列表中。如果待取消的文件正在上传中,则取消上传并自动上传下一个文件。
- (BOOL)cancelFile:(int)index;
恢复已取消的上传文件,并自动开始上传。
- (BOOL)resumeFile:(int)index;
上传控制
停止上传,如果有文件正在上传中,则取消上传。
- (BOOL)stop;
说明 停止上传后如需恢复上传,请调用resumeFile
恢复待上传文件,或者清空队列后重新添加文件上传。
暂停上传。
- (BOOL)pause;
恢复上传。
- (BOOL)resume;
回调处理
上传失败
上传失败时,会触发OnUploadFailedListener
回调。在该回调方法中,可以通过code
和message
查看具体原因,并在页面上提示。更多错误码信息,请参见错误码表和OSS错误码。
凭证过期处理
上传凭证或STS过期,会触发OnUploadTokenExpiredListener
回调。在该回调方法中,可以向AppServer重新请求新的上传凭证或STS,并调用以下方法继续上传。
重新设置上传凭证
- (BOOL)resumeWithAuth:(NSString *)uploadAuth;
重新设置STS
- (BOOL)resumeWithToken:(NSString *)accessKeyId
accessKeySecret:(NSString *)accessKeySecret
secretToken:(NSString *)secretToken
expireTime:(NSString *)expireTime;
超时处理
上传超时,会触发OnUploadRertyListener
回调并自动重试。在该回调方法中,可以在页面上给予提示或者调用stop
方法停止上传。此外,可以设置maxRetryCount
属性,指定最大重试次数。超时重试可以继续上传时,会触发OnUploadRertyResumeListener
回调并恢复上传。
高级设置
VODUploadClient
支持上传转码、超时重试、设置缓存文件夹位置、断点续传、分片上传、设置点播服务地域等高级设置。具体示例如下:
上传转码
/**
上传文件到服务端是否转码,默认值YES。指定视频转码生成的格式请参见:音视频转码。
*/
@property (nonatomic, assign) BOOL transcode;
超时重试
/**
最大超时重试次数,默认值INT_MAX
*/
@property (nonatomic, assign) uint32_t maxRetryCount;
/**
超时时间
*/
@property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;
设置缓存文件夹位置
/**
缓存文件夹位置
*/
@property (nonatomic, copy) NSString * recordDirectoryPath;
断点续传
/**
是否记录上传进度(断点续传),默认值YES
*/
@property (nonatomic, assign) BOOL recordUploadProgress;
分片上传
/**
分片大小,默认值1024 * 1024
*/
@property (nonatomic, assign) NSInteger uploadPartSize;
设置点播服务地域
/**
vod region,默认值"cn-shanghai"
*/
@property (nonatomic, copy) NSString *region;