准备工作
1. 您需要一个 Android 应用,这个应用可以是您现有的工程,也可以是您新建的一个空的工程。
2. 请确保您的 Android 应用目标为 API 级别 21 (Android 5.0) 或更高版本。
3. 您需要一个可以获取智能媒资托管服务访问令牌的业务服务端接口,访问令牌的相关说明请参见 生成访问令牌。
步骤1:安装 SDK
自动集成
使用 mavenCentral 仓库
在项目级别(通常是根目录下)的
build.gradle
中添加:repositories {google()// 增加这行mavenCentral()}
在应用级别(通常是 app 模块下)的
build.gradle
中添加依赖:dependencies {...// 增加这行implementation 'com.qcloud.cos:smh-android:1.1.8'}
关闭 beacon 上报功能
说明
腾讯灯塔只对 SMH 侧的请求性能进行监控,不会上报业务侧数据。
若是想关闭该功能,请在应用级别(通常是 app 模块下)的
build.gradle
中修改 smh-android 的依赖为:dependencies {...// 修改为implementation 'com.qcloud.cos:smh-android-nobeacon:1.1.8'}
步骤2:配置权限
网络权限
SDK 需要网络权限,用于与 SMH 服务器进行通信,请在应用模块下的
AndroidManifest.xml
中添加如下权限声明:<uses-permission android:name="android.permission.INTERNET"/>
存储权限
如果您的应用场景中需要从外部存储中读写文件,请在应用模块下的
AndroidManifest.xml
中添加如下权限声明:<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /><uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
注意
在 Android 6.0(API level 23)以上,您需要在运行时动态申请存储权限。
步骤3:开始使用
实现获取访问令牌
实现一个
SMHSimpleUser
的子类,实现获取 libraryId 和 userSpace、请求访问令牌并返回结果的过程。class MySMHSimpleUser: SMHSimpleUser() {override val libraryId: Stringget() = "smh3ptyc9mscifdi"override val userSpace: UserSpaceget() = UserSpace(userId = "7",spaceId = "space1x8mfjgno6nyy")override suspend fun provideAccessToken(): AccessToken {// 首先从您的访问令牌服务器获取包含了访问令牌信息的响应// 然后解析响应,获取访问令牌信息String token = "token"; // 访问令牌 Tokenlong expiresIn = 86400;// 访问令牌的有效时长,单位为秒//建议返回服务器时间作为签名的开始时间,避免由于用户手机本地时间偏差过大导致请求过期// 返回服务器时间作为签名的起始时间long startTime = 1556182000L; //访问令牌有效起始时间,单位是毫秒// 最后返回访问令牌信息对象return new AccessToken(token, startTime, expiresIn);}}
这里假设类名为
MySMHSimpleUser
。初始化一个实例,来给 SDK 提供访问令牌。val mySMHSimpleUser: MySMHSimpleUser = MySMHSimpleUser();
初始化 SMHCollection
使用您提供密钥的实例
mySMHSimpleUser
,初始化一个 SMHCollection
的实例。SMHCollection
提供了访问 SMH 的所有接口,建议作为程序单例使用,后续文档中的 SMH 均指创建的 SMHCollection 实例。// 初始化 SMHCollection,获取实例val smh: SMHCollection = SMHCollection(context = context,user = mySMHSimpleUser)
步骤4:访问 SMH 服务
例如:列出文件列表
//目标文件夹val targetDir = Directory()try {val directoryContents: DirectoryContents = smh.list(//目标目录dir = targetDir,//页码page = 1,//每页拉取的数量pageSize = 100,//排序方式orderType = OrderType.NAME,//排序方向orderDirection = OrderDirection.ASC,//过滤类型directoryFilter = DirectoryFilter.ONLY_FILE)//文件/目录列表 其他数量等内容请查看 DirectoryContents 实体内容val contents = directoryContents.contents} catch (e: Exception) {e.printStackTrace()}
通用参数介绍
LibraryId:媒体库 ID,必选参数。
SpaceId:空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数。
AccessToken:访问令牌,必选参数。
UserId:用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份,详情请参见 生成访问令牌,可选参数。
OrganizationId:组织 ID,必选参数。
UserToken:用户令牌,必选参数。
说明