相关资源
- SDK 源码下载请参见 XML Android SDK。
- 示例 Demo 请参见 XML Android SDK Demo。
- SDK 接口与参数文档请参见 SDK API 参考。
- SDK 文档中的所有示例代码请参见 SDK 代码示例。
- SDK 更新日志请参见 ChangeLog。
- SDK 常见问题请参见:Android SDK 常见问题。
说明:如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。如果您仍在使用 JSON 版本 SDK,请 升级到 XML Android SDK。
准备工作
- 您需要一个 Android 应用,这个应用可以是您现有的工程,也可以是您新建的一个空的工程。
- 请确保您的 Android 应用目标为 API 级别 15 (Ice Cream Sandwich) 或更高版本。
- 您需要一个可以获取腾讯云临时密钥的远程地址,关于临时密钥的有关说明请参考 移动应用直传实践。
第一步:安装 SDK
方式一:自动集成(推荐)
说明:bintray 仓库已经下线,COS SDK 已经迁移到 mavenCentral,引用路径和之前不同,您在更新的时候请使用新的引用路径。
使用 mavenCentral 仓库
在项目级别(通常是根目录下)的 build.gradle
中添加:
repositories {
google()
// 增加这行
mavenCentral()
}
标准版 SDK
在应用级别(通常是 app 模块下)的 build.gradle
中添加依赖:
dependencies {
...
// 增加这行
implementation 'com.qcloud.cos:cos-android:5.9.+'
}
精简版 SDK
在应用级别(通常是 app 模块下)的 build.gradle
中添加依赖:
dependencies {
...
// 增加这行
implementation 'com.qcloud.cos:cos-android-lite:5.9.+'
}
关闭 beacon 上报功能
为了持续跟踪和优化 SDK 的质量,给您带来更好的使用体验,我们在 SDK 中引入了 腾讯灯塔 SDK。
说明:腾讯灯塔只对COS侧的请求性能进行监控,不会上报业务侧数据。
若是想关闭该功能,请在应用级别(通常是 app 模块下)的 build.gradle
中进行如下操作:
版本为5.8.0以及以上:
修改 cos-android 的依赖为
dependencies {
...
// 修改为
implementation 'com.qcloud.cos:cos-android-nobeacon:x.x.x'
//lite版本修改为
implementation 'com.qcloud.cos:cos-android-lite-nobeacon:x.x.x'
}
版本为5.5.8至5.7.9:
添加去掉 beacon 的语句
dependencies {
...
implementation ('com.qcloud.cos:cos-android:x.x.x'){
// 增加这行
exclude group: 'com.tencent.qcloud', module: 'beacon-android-release'
}
}
方式二:手动集成
1. 下载归档文件
您可以通过 快速下载地址 下载最新的正式包,也可以在 SDK Releases 里面找到我们所有历史版本的正式包。
下载完成并解压后,您可以看到里面包含了数个 jar
或 aar
包。下面是对它们的简单说明,请根据需要选择集成的包。
必选的库:
- cos-android:COS 协议实现
- qcloud-foundation:基础库
- bolts-tasks:第三方 Task 库
- okhttp:第三方 Networking 库
- okio:第三方 IO 库
可选的库:
- quic:QUIC 协议,当您使用到 QUIC 协议来传输数据时需要
- beacon: beacon 移动分析,用于改进 SDK
2. 集成到项目中
把需要的包放到您应用模块下的 libs
文件夹下,并在应用级别(通常是 app 模块下)的 build.gradle
文件中添加如下依赖:
dependencies {
...
// 增加这行
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}
第二步:配置权限
网络权限
SDK 需要网络权限,用于与 COS 服务器进行通信,请在应用模块下的 AndroidManifest.xml
中添加如下权限声明:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
存储权限
如果您的应用场景中需要从外部存储中读写文件,请在应用模块下的 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)以上,您需要在运行时动态申请存储权限。
第三步:开始使用
1. 实现获取临时密钥
实现一个 BasicLifecycleCredentialProvider
的子类,实现请求临时密钥并返回结果的过程。
public static class MySessionCredentialProvider
extends BasicLifecycleCredentialProvider {
@Override
protected QCloudLifecycleCredentials fetchNewCredentials()
throws QCloudClientException {
// 首先从您的临时密钥服务器获取包含了密钥信息的响应
// 然后解析响应,获取临时密钥信息
String tmpSecretId = "SECRETID"; // 临时密钥 SecretId
String tmpSecretKey = "SECRETKEY"; // 临时密钥 SecretKey
String sessionToken = "SESSIONTOKEN"; // 临时密钥 Token
long expiredTime = 1556183496L;//临时密钥有效截止时间戳,单位是秒
//建议返回服务器时间作为签名的开始时间,避免由于用户手机本地时间偏差过大导致请求过期
// 返回服务器时间作为签名的起始时间
long startTime = 1556182000L; //临时密钥有效起始时间,单位是秒
// 最后返回临时密钥信息对象
return new SessionQCloudCredentials(tmpSecretId, tmpSecretKey,
sessionToken, startTime, expiredTime);
}
}
这里假设类名为 MySessionCredentialProvider
。初始化一个实例,来给 SDK 提供密钥。
QCloudCredentialProvider myCredentialProvider = new MySessionCredentialProvider();
使用永久密钥进行本地调试
您可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄漏密钥的风险,请务必在上线前替换为临时密钥的方式。
String secretId = "SECRETID"; //永久密钥 secretId
String secretKey = "SECRETKEY"; //永久密钥 secretKey
// keyDuration 为请求中的密钥有效期,单位为秒
QCloudCredentialProvider myCredentialProvider =
new ShortTimeCredentialProvider(secretId, secretKey, 300);
2. 初始化 COS Service
使用您提供密钥的实例 myCredentialProvider
,初始化一个 CosXmlService
的实例。
CosXmlService
提供了访问 COS 的所有接口,建议作为 程序单例 使用。
// 存储桶所在地域简称,例如广州地区是 ap-guangzhou
String region = "COS_REGION";
// 创建 CosXmlServiceConfig 对象,根据需要修改默认的配置参数
CosXmlServiceConfig serviceConfig = new CosXmlServiceConfig.Builder()
.setRegion(region)
.isHttps(true) // 使用 HTTPS 请求, 默认为 HTTP 请求
.builder();
// 初始化 COS Service,获取实例
CosXmlService cosXmlService = new CosXmlService(context,
serviceConfig, myCredentialProvider);
说明:关于存储桶不同地域的简称请参考 地域和访问域名。
第四步:访问 COS 服务
上传对象
SDK 支持上传本地文件、二进制数据、Uri 以及输入流。下面以上传本地文件为例:
// 初始化 TransferConfig,这里使用默认配置,如果需要定制,请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
transferConfig);
// 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键
String srcPath = new File(context.getCacheDir(), "exampleobject")
.toString(); //本地文件的绝对路径
//若存在初始化分块上传的 UploadId,则赋值对应的 uploadId 值用于续传;否则,赋值 null
String uploadId = null;
// 上传文件
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
srcPath, uploadId);
//设置上传进度回调
cosxmlUploadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long complete, long target) {
// todo Do something to update progress...
}
});
//设置返回结果回调
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) result;
}
// 如果您使用 kotlin 语言来调用,请注意回调方法中的异常是可空的,否则不会回调 onFail 方法,即:
// clientException 的类型为 CosXmlClientException?,serviceException 的类型为 CosXmlServiceException?
@Override
public void onFail(CosXmlRequest request,
@Nullable CosXmlClientException clientException,
@Nullable CosXmlServiceException serviceException) {
if (clientException != null) {
clientException.printStackTrace();
} else {
serviceException.printStackTrace();
}
}
});
//设置任务状态回调, 可以查看任务过程
cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
@Override
public void onStateChanged(TransferState state) {
// todo notify transfer state
}
});
说明:
下载对象
// 高级下载接口支持断点续传,所以会在下载前先发起 HEAD 请求获取文件信息。
// 如果您使用的是临时密钥或者使用子账号访问,请确保权限列表中包含 HeadObject 的权限。
// 初始化 TransferConfig,这里使用默认配置,如果需要定制,请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
//初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
transferConfig);
// 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键
//本地目录路径
String savePathDir = context.getExternalCacheDir().toString();
//本地保存的文件名,若不填(null),则与 COS 上的文件名一样
String savedFileName = "exampleobject";
Context applicationContext = context.getApplicationContext(); // application
// context
COSXMLDownloadTask cosxmlDownloadTask =
transferManager.download(applicationContext,
bucket, cosPath, savePathDir, savedFileName);
//设置下载进度回调
cosxmlDownloadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long complete, long target) {
// todo Do something to update progress...
}
});
//设置返回结果回调
cosxmlDownloadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLDownloadTask.COSXMLDownloadTaskResult downloadTaskResult =
(COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
}
// 如果您使用 kotlin 语言来调用,请注意回调方法中的异常是可空的,否则不会回调 onFail 方法,即:
// clientException 的类型为 CosXmlClientException?,serviceException 的类型为 CosXmlServiceException?
@Override
public void onFail(CosXmlRequest request,
@Nullable CosXmlClientException clientException,
@Nullable CosXmlServiceException serviceException) {
if (clientException != null) {
clientException.printStackTrace();
} else {
serviceException.printStackTrace();
}
}
});
//设置任务状态回调,可以查看任务过程
cosxmlDownloadTask.setTransferStateListener(new TransferStateListener() {
@Override
public void onStateChanged(TransferState state) {
// todo notify transfer state
}
});
说明:
- 更多完整示例,请前往 GitHub 查看。
- 高级下载接口支持断点续传,所以会在下载前先发起 HEAD 请求获取文件信息。如果您使用的是临时密钥或者使用子账号访问,请确保权限列表中包含 HeadObject 的权限。