说明:如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。
说明:bintray 仓库已经下线,COS SDK 已经迁移到 mavenCentral,引用路径和之前不同,您在更新的时候请使用新的引用路径。
在项目级别(通常是根目录下)的 build.gradle
中添加:
repositories {
google()
// 增加这行
mavenCentral()
}
在应用级别(通常是 app 模块下)的 build.gradle
中添加依赖:
dependencies {
...
// 增加这行
implementation 'com.qcloud.cos:cos-android:5.7.+'
}
在应用级别(通常是 app 模块下)的 build.gradle
中添加依赖:
dependencies {
...
// 增加这行
implementation 'com.qcloud.cos:cos-android-lite:5.7.+'
}
为了持续跟踪和优化 SDK 的质量,给您带来更好的使用体验,我们在 SDK 中引入了 腾讯灯塔 SDK。
说明:腾讯灯塔只对COS侧的请求性能进行监控,不会上报业务侧数据。
若是想关闭该功能,请在应用级别(通常是 app 模块下)的 build.gradle
中添加去掉 beacon 的语句:
dependencies {
...
implementation ('com.qcloud.cos:cos-android:x.x.x'){
// 增加这行
exclude group: 'com.tencent.qcloud', module: 'beacon-android-release'
}
}
您可以通过 快速下载地址 下载最新的正式包,也可以在 SDK Releases 里面找到我们所有历史版本的正式包。
下载完成并解压后,您可以看到里面包含了数个 jar
或 aar
包。下面是对它们的简单说明,请根据需要选择集成的包。
必选的库:
可选的库:
把需要的包放到您应用模块下的 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)以上,您需要在运行时动态申请存储权限。
实现一个 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);
使用您提供密钥的实例 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);
说明:关于存储桶不同地域的简称请参考 地域和访问域名。
SDK 支持上传本地文件、二进制数据、Uri 以及输入流。下面以上传本地文件为例:
// 初始化 TransferConfig,这里使用默认配置,如果需要定制,请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
transferConfig);
// 存储桶名称,由bucketname-appid 组成,appid必须填入,可以在COS控制台查看存储桶名称。 https://console.intl.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.intl.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 的权限。
本页内容是否解决了您的问题?