本文介绍如何使用iOS端上传SDK完成媒体上传。

前提条件

您已经集成视频点播提供的iOS上传SDK。具体操作,请参见集成SDK。Demo下载,请参见客户端上传SDKiOS下载。

上传文件

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

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

    iOS上传SDK支持以下两种上传授权方式:

    执行结果

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

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

    初始化上传实例分为声明初始化回调和初始化上传实例两步。

    1. 声明VODUploadClient属性,不能是局部变量。
    2. 初始化上传实例。请根据业务需求选择用上传地址和凭证方式STS方式初始化上传实例。
      • 上传地址和凭证方式(推荐)
        说明
        • 上传地址和凭证方式调用init方法初始化。
        • 使用获取的上传地址和凭证初始化时无需设置,在开始上传后触发的OnUploadStartedListener回调中调用setUploadAuthAndAddress: uploadAuth:uploadAddress:方法进行设置。
        • 当token超时,会触发OnUploadTokenExpiredListener回调,需要调用resumeWithAuth方法,设置新的上传凭证继续上传。
        //创建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];
  3. 设置回调,用于接收上传过程中关键节点的消息。

    设置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);
  4. 根据上传的文件类型(音视频或图片)构造上传参数。
    说明 音视频和图片的上传参数略有差异。目前客户端不支持上传辅助媒资。
    音视频文件参数

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

    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];
  5. 开始上传。
    1. 调用start开始上传。
      [self.uploader start];
      该方法调用后,会触发OnUploadStartedListener回调。如果通过上传地址和凭证方式上传,需要在该回调方法中设置上传地址和凭证。代码如下:
      [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:weakSelf.uploadAuth uploadAddress:weakSelf.uploadAddress];
    2. 文件开始上传后,OnUploadProgressListener回调开始同步上传进度。

      回调参数包括已上传文件大小uploadedSize和总文件大小totalSize

    3. 文件上传成功后,OnUploadFinishedListener回调会返回上传文件信息UploadFileInfo和上传结果VodUploadResult
      VodUploadResult包含以下属性:
      @property (nonatomic, copy) NSString* videoId;
      @property (nonatomic, copy) NSString* imageUrl;
      说明 videoId只在STS方式上传视频成功后才有返回值,imageUrl只在STS方式上传图片成功后才有返回值。如果使用上传地址和凭证方式上传,videoIdimageUrl不会返回,相应的值在请求上传地址和凭证时就可以获取到。
执行结果
  • 视频上传成功后会返回videoId作为视频ID,拿到videoId之后需要获取播放地址进行播放。更多信息,请参见获取播放地址播放
  • 图片上传完成后会返回imageUrl,开启URL鉴权后imageUrl会有过期时间。更多信息,请参见URL鉴权

队列管理

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回调。在该回调方法中,可以通过codemessage查看具体原因,并在页面上提示。更多错误码信息,请参见错误码表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;