全部产品
云市场

文件上传

更新时间:2019-06-12 10:59:42

简介

点播文件上传VODUploadClient,支持上传地址加凭证或STS方式上传,推荐使用上传地址加凭证方式上传。

整体步骤

  1. 请求上传地址加凭证或STS,相关概念请参见相关文档。
  2. 初始化上传实例,实例化上传有两种方式:上传地址加凭证和STS方式。
  3. 回调设置,所有的上传状态包括进度,上传成功,上传失败,凭证过期都在这里进行处理。
  4. 添加上传文件进入上传列表,目前主要支持视频文件和图片文件的上传。
  5. 启动上传
  6. 回调处理

1. 请求上传地址加凭证或STS

1.1 请求上传地址加凭证

上传图片和上传视频获取上传地址和凭证所请求的API是不同的。

客户端上传视频:需要请求向AppServer发送请求,AppServer通过OpenApi向阿里云点播服务发送CreateUploadVideo请求。请求成功将返回上传地址,上传凭证以及VideoId,AppServer需要将结果返回给客户端。

客户端上传图片:需要请求向AppServer发送请求,AppServer通过OpenApi向阿里云点播服务发送CreateUploadImage请求。请求成功将返回上传地址,上传凭证以及ImageURL,AppServer需要将结果返回给客户端。

1.2 请求STS

通过STS方式,客户端需要向AppServer发送请求,AppServer向阿里云STS服务请求临时STS凭证。请求成功将返回STS凭证,AppServer需要将结果返回给客户端。

2. 初始化

首先,声明VODUploadClient属性,注意不能是局部变量。

  1. @property (nonatomic, strong) VODUploadClient *uploader;

2.1 上传地址和凭证方式

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

第一步请求获取的上传地址和凭证初始化时无需设置,而是在开始上传开始后触发的OnUploadStartedListener回调中调用setUploadAuthAndAddress: uploadAuth:uploadAddress:方法进行设置。

当token超时,会触发OnUploadTokenExpiredListener回调,需要调用resumeWithAuth:方法,设置新的上传凭证继续上传。

  1. // create VODUploadClient object
  2. self.uploader = [VODUploadClient new];
  3. // weakself
  4. __weak typeof(self) weakSelf = self;
  5. // setup callback
  6. OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
  7. NSLog(@"upload finished callback videoid:%@, imageurl:%@", result.videoId, result.imageUrl);
  8. };
  9. OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
  10. NSLog(@"upload failed callback code = %@, error message = %@", code, message);
  11. };
  12. OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
  13. NSLog(@"upload progress callback uploadedSize : %li, totalSize : %li", uploadedSize, totalSize);
  14. };
  15. OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
  16. NSLog(@"upload token expired callback.");
  17. // token过期,设置新的上传凭证,继续上传
  18. [weakSelf.uploader resumeWithAuth:`new upload auth`];
  19. };
  20. OnUploadRertyListener RetryCallbackFunc = ^{
  21. NSLog(@"upload retry begin callback.");
  22. };
  23. OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
  24. NSLog(@"upload retry end callback.");
  25. };
  26. OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
  27. NSLog(@"upload upload started callback.");
  28. // 设置上传地址 和 上传凭证
  29. [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:`upload auth` uploadAddress:`upload address`];
  30. };
  31. VODUploadListener *listener = [[VODUploadListener alloc] init];
  32. listener.finish = FinishCallbackFunc;
  33. listener.failure = FailedCallbackFunc;
  34. listener.progress = ProgressCallbackFunc;
  35. listener.expire = TokenExpiredCallbackFunc;
  36. listener.retry = RetryCallbackFunc;
  37. listener.retryResume = RetryResumeCallbackFunc;
  38. listener.started = UploadStartedCallbackFunc;
  39. // init with upload address and upload auth
  40. [self.uploader init:listener];

2.2 STS方式

STS方式调用init: accessKeySecret: secretToken: expireTime: listener:方法初始化,初始化参数即是第一步请求获取的临时STS凭证。

当token过期时,触发OnUploadTokenExpiredListener回调,需要调用resumeWithToken: accessKeySecret: secretToken: expireTime:方法,设置新的STS继续上传。

  1. // create VODUploadClient object
  2. self.uploader = [VODUploadClient new];
  3. // weakself
  4. __weak typeof(self) weakSelf = self;
  5. // setup callback
  6. OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
  7. NSLog(@"upload finished callback videoid:%@, imageurl:%@", result.videoId, result.imageUrl);
  8. };
  9. OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
  10. NSLog(@"upload failed callback code = %@, error message = %@", code, message);
  11. };
  12. OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
  13. NSLog(@"upload progress callback uploadedSize : %li, totalSize : %li", uploadedSize, totalSize);
  14. };
  15. OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
  16. NSLog(@"upload token expired callback.");
  17. // token过期,设置新的STS,继续上传
  18. [weakSelf.uploader resumeWithToken:`STS Key Id` accessKeySecret:`STS Key Secret` secretToken:`STS Secret Token` expireTime:`STS Expire Time`];
  19. };
  20. OnUploadRertyListener RetryCallbackFunc = ^{
  21. NSLog(@"upload retry begin callback.");
  22. };
  23. OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
  24. NSLog(@"upload retry end callback.");
  25. };
  26. OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
  27. NSLog(@"upload upload started callback.");
  28. };
  29. // init
  30. VODUploadListener *listener = [[VODUploadListener alloc] init];
  31. listener.finish = FinishCallbackFunc;
  32. listener.failure = FailedCallbackFunc;
  33. listener.progress = ProgressCallbackFunc;
  34. listener.expire = TokenExpiredCallbackFunc;
  35. listener.retry = RetryCallbackFunc;
  36. listener.retryResume = RetryResumeCallbackFunc;
  37. listener.started = UploadStartedCallbackFunc;
  38. // init with STS
  39. [self.uploader init:`STS Key Id` accessKeySecret:`STS Key Secret` secretToken:STS Secret Token` expireTime:`STS Expire Time` listener:listener];

3. 回调设置

从初始化代码片段中可以看到,两种方法初始化都需要设置VODUploadListener对象,该对象是上传状态的回调类,需要设置下列回调方法:

  1. /**
  2. 上传完成回调
  3. @param fileInfo 上传文件信息
  4. @param result 上传结果信息
  5. */
  6. typedef void (^OnUploadFinishedListener) (UploadFileInfo* fileInfo, VodUploadResult* result);
  7. /**
  8. 上传失败回调
  9. @param fileInfo 上传文件信息
  10. @param code 错误码
  11. @param message 错误描述
  12. */
  13. typedef void (^OnUploadFailedListener) (UploadFileInfo* fileInfo, NSString *code, NSString * message);
  14. /**
  15. 上传进度回调
  16. @param fileInfo 上传文件信息
  17. @param uploadedSize 已上传大小
  18. @param totalSize 总大小
  19. */
  20. typedef void (^OnUploadProgressListener) (UploadFileInfo* fileInfo, long uploadedSize, long totalSize);
  21. /**
  22. token过期回调
  23. 上传地址和凭证方式上传需要调用resumeWithAuth:方法继续上传
  24. STS方式上传需要调用resumeWithToken:accessKeySecret:secretToken:expireTime:方法继续上传
  25. */
  26. typedef void (^OnUploadTokenExpiredListener) ();
  27. /**
  28. 上传开始重试回调
  29. */
  30. typedef void (^OnUploadRertyListener) ();
  31. /**
  32. 上传结束重试,继续上传回调
  33. */
  34. typedef void (^OnUploadRertyResumeListener) ();
  35. /**
  36. 开始上传回调
  37. 上传地址和凭证方式上传需要调用setUploadAuthAndAddress:uploadAuth:uploadAddress:方法设置上传地址和凭证
  38. @param fileInfo 上传文件信息
  39. */
  40. typedef void (^OnUploadStartedListener) (UploadFileInfo* fileInfo);

4. 添加文件到上传列表

4.1 添加文件

添加视频

  1. NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"mp4"];
  2. VodInfo *vodInfo = [[VodInfo alloc] init];
  3. vodInfo.title = @"title";
  4. vodInfo.desc =@"desc";
  5. vodInfo.cateId = @(19);
  6. vodInfo.tags = @"sports";
  7. [self.uploader addFile:filePath vodInfo:vodInfo];

添加图片

  1. NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"jpg"];
  2. VodInfo *imageInfo = [[VodInfo alloc] init];
  3. imageInfo.title = @"title";
  4. imageInfo.desc =@"desc";
  5. imageInfo.cateId = @(19);
  6. imageInfo.tags = @"sports";
  7. [self.uploader addFile:filePath vodInfo:imageInfo];

> 注意:支持的文件大小<=4G。

VodInfo具体结构如下:

  1. //标题
  2. @property (nonatomic, copy) NSString* title;
  3. //标签
  4. @property (nonatomic, copy) NSString* tags;
  5. //描述
  6. @property (nonatomic, copy) NSString* desc;
  7. //分类id
  8. @property (nonatomic, strong) NSNumber* cateId;
  9. //封面url (完整的URL https://)
  10. @property (nonatomic, copy) NSString* coverUrl;

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

  1. //文件本地路径
  2. @property (nonatomic, copy) NSString* filePath;
  3. //endpoint
  4. @property (nonatomic, copy) NSString* endpoint;
  5. //bucket
  6. @property (nonatomic, copy) NSString* bucket;
  7. //object
  8. @property (nonatomic, copy) NSString* object;
  9. //VodInfo
  10. @property (nonatomic, strong) VodInfo* vodInfo;

4.2 管理上传队列

VODUploadClient支持添加多个文件顺序上传,提供了以下方法管理上传队列。从队列中删除上传文件。如果待删除的文件正在上传中,则取消上传并自动上传下一个文件:

  1. - (BOOL)deleteFile:(int) index;

清空上传队列,如果有文件在上传,则取消上传:

  1. - (BOOL)clearFiles;

获取上传文件队列:

  1. - (NSMutableArray<UploadFileInfo *> *)listFiles;

将文件标记为取消,文件任保留在上传列表中。如果待取消的文件正在上传中,则取消上传并自动上传下一个文件:

  1. - (BOOL)cancelFile:(int)index;

恢复已取消的上传文件,并自动开始上传:

  1. - (BOOL)resumeFile:(int)index;

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

5. 上传控制

开始上传:

  1. [self.uploader start];

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

  1. [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:weakSelf.uploadAuth uploadAddress:weakSelf.uploadAddress];

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

  1. - (BOOL)stop;

> stop后恢复上传需要调用resumeFile:恢复待上传文件,或者清空队列后重新添加文件上传。

暂停上传:

  1. - (BOOL)pause;

恢复上传:

  1. - (BOOL)resume;

6. 回调处理

6.1 上传进度

每上传一个分片,会触发OnUploadProgressListener回调,回调参数包括已上传文件大小uploadedSize和总文件大小totalSize

6.2 上传成功

上传成功时,会触发OnUploadFinishedListener回调。回调包含上传文件信息UploadFileInfo和上传结果VodUploadResultVodUploadResult包含以下属性:

  1. @property (nonatomic, copy) NSString* videoId;
  2. @property (nonatomic, copy) NSString* imageUrl;

需要注意,videoId只在STS方式上传视频成功后才有返回值,imageUrl只在STS方式上传图片成功后才有返回值。如果使用上传地址加凭证方式上传,videoIdimageUrl不会返回,相应的值在请求上传地址加凭证时就可以获取到。

> 视频上传成功后会返回videoId作为视频id,拿到videoId之后需要获取播放地址进行播放。相关文档可以参考获取播放地址播放。> 图片上完成后会返回imageUrl,开启URL鉴权后imageUrl会有过期时间。相关配置可以参考URL鉴权

6.3 上传失败

上传失败时,会触发OnUploadFailedListener回调。在该回调方法中,我们可以通过codemessage查看具体原因,页面上给予用户提示。错误码参见:点播错误码oss错误码

6.4 凭证过期处理

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

重新设置上传凭证

  1. - (BOOL)resumeWithAuth:(NSString *)uploadAuth;

重新设置STS

  1. - (BOOL)resumeWithToken:(NSString *)accessKeyId
  2. accessKeySecret:(NSString *)accessKeySecret
  3. secretToken:(NSString *)secretToken
  4. expireTime:(NSString *)expireTime;

6.5 超时处理

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

高级设置

VODUploadClient支持以下高级设置:

  1. /**
  2. 上传文件到服务端是否转码,默认值YES
  3. */
  4. @property (nonatomic, assign) BOOL transcode;
  5. /**
  6. 最大超时重试次数,默认值INT_MAX
  7. */
  8. @property (nonatomic, assign) uint32_t maxRetryCount;
  9. /**
  10. 超时时间
  11. */
  12. @property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;
  13. /**
  14. 缓存文件夹位置
  15. */
  16. @property (nonatomic, copy) NSString * recordDirectoryPath;
  17. /**
  18. 是否记录上传进度(断点续传),默认值YES
  19. */
  20. @property (nonatomic, assign) BOOL recordUploadProgress;
  21. /**
  22. 分片大小,默认值1024 * 1024
  23. */
  24. @property (nonatomic, assign) NSInteger uploadPartSize;
  25. /**
  26. vod region,默认值"cn-shanghai"
  27. */
  28. @property (nonatomic, copy) NSString *region;