使用iOS SDK上传媒体文件-视频点播-阿里云

本文介绍如何使用iOS SDK将媒体文件从本地上传至点播存储。

前提条件

iOS终端系统版本为iOS8或以上版本。
iOS上传SDK暂不支持使用Swift语言编程。

集成SDK

集成方式

Pod方式集成SDK（推荐）

执行pod 'VODUpload'命令，在Podfile文件中添加VOD上传SDK库的依赖。
执行pod repo update命令，更新pod repo。
执行pod install命令，安装VOD上传SDK库。

手动方式集成

SDK版本：1.6.5
更新时间：2022-01-24
下载包MD5值：f3551634b53cd1264013db4762f79a14
下载地址：V1.6.5 SDK

在Xcode中，把VODUpload.framework和AliyunOSSiOS.framework拖入项目Target下，在弹出提示框中选中Copy items if needed。
添加以下系统依赖库。
1. AVFoundation.framework
2. CoreMedia.framework
3. SystemConfiguration.framework
4. MobileCoreServices.framework
5. libresolv.9.tbd

项目配置

SDK集成后，打开项目工程并按照以下步骤修改配置。

单击菜单栏上Build Setting > Linking > Other Linker Flags。
添加-Objc。

基础设置

初始化上传实例

请先了解客户端上传的整体上传流程，并根据上传的授权方式部署对应的授权服务：

选择使用上传地址和凭证方式，请在授权服务中获取上传地址和凭证。
选择使用STS Token方式，请在授权服务中获取STS Token。

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

声明VODUploadClient属性，不能是局部变量。

初始化上传实例。

上传地址和凭证方式

说明

上传地址和凭证方式调用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 Token方式

说明

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];

开始上传。
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方式上传图片成功后才有返回值。如果使用上传地址和凭证方式上传，videoId和imageUrl不会返回，相应的值在请求上传地址和凭证时就可以获取到。

执行结果

视频上传成功后会返回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回调。在该回调方法中，可以通过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支持上传加速、上传转码、超时重试、设置缓存文件夹位置、断点续传、分片上传、设置点播服务地域等高级设置。具体示例如下：

上传加速

当您需要上传较大文件（GB、TB级别）或进行跨区域上传（比如在中国内地将视频上传到新加坡存储地域的存储地址）时，您可以启用上传加速功能。详情请参见开通方式。开通后需要您在上传实例的vodInfo配置中的UserData字符串赋值增加相应的key-value值（以Jsontring的方式传递）。示例如下：

/** 
VodInfo 设置自定义数据 
*/
@property (nonatomic, copy) NSString *UserData;
vodInfo.UserData = "{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}";

参数描述

名称	类型	说明
Type	string	开启上传加速的类型（仅支持oss）。
Domain	string	用户bucket的加速地址（默认为https）。说明使用开通后分配的一个加速地址，例如：vod-*******.oss-accelerate.aliyuncs.com。

上传转码

/**
 上传文件到服务端是否转码，默认值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;