准备工作
1. 您需要一个 iOS 应用,这个应用可以是您现有的工程,也可以是您新建的一个空的工程。
2. 请确保您的 iOS 应用目标为 iOS 9及以上。
步骤1:安装 SDK
Pod 集成
SDK 分为四个模块,可以按照项目实际需求集成相应模块,推荐集成 SDK 完整功能。
名称 | 功能描述 | 集成 |
Default | SDK 完整功能,包括 API、User、灯塔数据收集三个模块 | pod "QCloudCOSSMH" |
Slim | API、User 模块,排除灯塔数据收集模块 | pod "QCloudCOSSMH/Slim" |
Api | API 模块 | pod "QCloudCOSSMH/Api" |
User | User 模块 | pod "QCloudCOSSMH/User" |
步骤2:开始使用
导入头文件
Default 和 Slim
#import <QCloudCOSSMH.h>
Api
#import <QCloudCOSSMHApi.h>
User
#import <QCloudCOSSMHUser.h>
初始化 SMH 服务并实现获取 accessToken 协议
说明
User 模块不需要 accesstoken,若仅使用 User,可以跳过此步骤。
集成 API 和 User 时,获取 accessToken 的方式。
API 模块接口在发出请求时需要携带 accesstoken,所以需要实现 QCloudSMHAccessTokenProvider 协议,在该协议中获取包含 accesstoken 以及 spaceid 等信息的 QCloudSMHSpaceInfo 对象通过参数 continueBlock 回调给 SDK。
- (void)accessTokenWithRequest:(QCloudSMHBizRequest *)requesturlRequest:(NSURLRequest *)urlRequstcompelete:(QCloudSMHAuthentationContinueBlock)continueBlock {if (!request.spaceId.length) {// 获取用户个人空间的 accesstoken,若用户只有个人空间时,没有 spaceid,因此需要调用该接口。QCloudSMHGetAccessTokenRequest *getAccessToken = [QCloudSMHGetAccessTokenRequest new];getAccessToken.priority = QCloudAbstractRequestPriorityHigh;// 用户所在组织 IDgetAccessToken.organizationId = @"organizationId";// User 模块中登录接口返回getAccessToken.userToken = @"userToken";[getAccessToken setFinishBlock:^(QCloudSMHSpaceInfo *outputObject, NSError *_Nullable error) {continueBlock(outputObject, error);}];// 发起请求[[QCloudSMHUserService defaultSMHUserService] getAccessToken:getAccessToken];}else{// 根据spaceid获取指定空间accesstoken。QCloudSMHGetSpaceAccessTokenRequest *getAccessToken = [QCloudSMHGetSpaceAccessTokenRequest new];getAccessToken.priority = QCloudAbstractRequestPriorityHigh;// // 用户所在组织 IDgetAccessToken.organizationId = @"organizationId";// User 模块中登录接口返回getAccessToken.userToken = @"userToken";// 空间 IDgetAccessToken.spaceId = request.spaceId;// 空间所在组织 ID,当前用户需要访问外部组织的空间时,需要设置该参数getAccessToken.spaceOrgId = request.spaceOrgId;[getAccessToken setFinishBlock:^(QCloudSMHSpaceInfo *outputObject, NSError *_Nullable error) {continueBlock(outputObject, error);}];[[QCloudSMHUserService defaultSMHUserService] getSpaceAccessToken:getAccessToken];}}
SDK 提供了一个 QCloudSMHAccessTokenFenceQueue 的脚手架,实现对 accessToken 的缓存与复用。脚手架在密钥过期之后会重新调用该协议的方法来重新获取新的密钥,直到该密钥过期时间大于设备的当前时间。
说明
建议把初始化过程放在 AppDelegate 或者程序单例中。
使用脚手架您需要实现
QCloudAccessTokenFenceQueueDelegate
协议。1. 初始化脚手架。
@property (nonatomic) QCloudSMHAccessTokenFenceQueue *fenceQueue;self.fenceQueue = [QCloudSMHAccessTokenFenceQueue new];self.fenceQueue.delegate = self;
2. 实现 QCloudAccessTokenFenceQueueDelegate。
- (void)fenceQueue:(QCloudSMHAccessTokenFenceQueue *)queuerequest:(QCloudSMHBizRequest *)requestrequestCreatorWithContinue:(QCloudAccessTokenFenceQueueContinue)continueBlock {if (!request.spaceId.length) {// 获取用户个人空间的accesstoken,若用户只有个人空间时,没有spaceid,因此需要调用该接口。QCloudSMHGetAccessTokenRequest *getAccessToken = [QCloudSMHGetAccessTokenRequest new];getAccessToken.priority = QCloudAbstractRequestPriorityHigh;// 用户所在组织idgetAccessToken.organizationId = @"organizationId";// User模块中登录接口返回getAccessToken.userToken = @"userToken";[getAccessToken setFinishBlock:^(QCloudSMHSpaceInfo *outputObject, NSError *_Nullable error) {continueBlock(outputObject, error);}];// 发起请求[[QCloudSMHUserService defaultSMHUserService] getAccessToken:getAccessToken];}else{// 根据spaceid获取指定空间accesstoken。QCloudSMHGetSpaceAccessTokenRequest *getAccessToken = [QCloudSMHGetSpaceAccessTokenRequest new];getAccessToken.priority = QCloudAbstractRequestPriorityHigh;// // 用户所在组织idgetAccessToken.organizationId = @"organizationId";// User模块中登录接口返回getAccessToken.userToken = @"userToken";// 空间idgetAccessToken.spaceId = request.spaceId;// 空间所在组织id,当前用户需要访问外部组织的空间时,需要设置该参数getAccessToken.spaceOrgId = request.spaceOrgId;[getAccessToken setFinishBlock:^(QCloudSMHSpaceInfo *outputObject, NSError *_Nullable error) {continueBlock(outputObject, error);}];[[QCloudSMHUserService defaultSMHUserService] getSpaceAccessToken:getAccessToken];}}// 在该方法中使用脚手架进行请求sdk内部缓存的accesstoken并使用continueBlock回调给sdk,若// sdk内缓存的accesstoken过期或没有,则跳转到上面方法中进行请求最新的accesstoken回调给sdk并缓存。- (void)accessTokenWithRequest:(QCloudSMHBizRequest *)requesturlRequest:(NSURLRequest *)urlRequstcompelete:(QCloudSMHAuthentationContinueBlock)continueBlock {[self.fenceQueue performRequest:requestwithAction:^(QCloudSMHSpaceInfo *_Nonnull accessToken, NSError *_Nonnull error) {if (error) {continueBlock(nil, error);} else {continueBlock(accessToken, nil);}}];}
说明
实现 QCloudSMHAccessTokenProvider 协议,在该协议中获取 accesstoken 并包装成一个 QCloudSMHSpaceInfo 对象通过参数 continueBlock 回调给 SDK。
步骤3:访问 SMH 服务
例如:列出文件列表。
QCloudSMHListContentsRequest *req = [QCloudSMHListContentsRequest new];// 用户所在空间 IDreq.spaceId = @"spaceId";// 用户所在 libraryidreq.libraryId = @"libraryId";// 用户 IDreq.userId = @"userId";// 目录路径或相簿名,对于多级目录,使用斜杠(/)分隔,例如 foo/bar;对于根目录,该参数留空;req.dirPath = @"dirpath";[req setFinishBlock:^(QCloudSMHContentListInfo *_Nullable result, NSError *_Nullable error) {// result 文件列表数据// error 报错信息}];// 发起请求[[QCloudSMHService defaultSMHService] listContents:req];
说明
SMH SDK 提供了自定义域名的功能,若业务有自研后台,可以使用如下方式更改访问域名,按需配置。
// 配置发布域名[QCloudSMHBaseRequest setBaseRequestHost:@"releasehost" targetType:QCloudECDTargetRelease];// 配置预发布域名[QCloudSMHBaseRequest setBaseRequestHost:@"previewhost" targetType:QCloudECDTargetPreview];// 配置测试域名[QCloudSMHBaseRequest setBaseRequestHost:@"testhost" targetType:QCloudECDTargetTest];// 配置开发域名[QCloudSMHBaseRequest setBaseRequestHost:@"devhost" targetType:QCloudECDTargetDevelop];// 设置当前模式 开发、测试、预发布、发布[QCloudSMHBaseRequest setTargetType:QCloudECDTarget];
通用参数介绍
LibraryId:媒体库 ID,必选参数。
SpaceId:空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数。
AccessToken:访问令牌,必选参数。
UserId:用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份,详情请参见 生成访问令牌,可选参数。
OrganizationId:组织 ID,必选参数。
UserToken:用户令牌,必选参数。