开发者指南

API 文档

SDK 文档

快速入门

最近更新时间:2020-08-07 15:08:21

相关资源

准备工作

  1. 您需要一个 Android 应用,这个应用可以是您现有的工程,也可以是您新建的一个空的工程。
  2. 请确保您的 Android 应用目标为 API 级别 15 (Ice Cream Sandwich) 或更高版本。
  3. 您需要一个可以获取腾讯云临时密钥的远程地址,关于临时密钥的有关说明请参考 移动应用直传实践

第一步:安装 SDK

方式一:自动集成(推荐)

标准版 SDK

在应用级别(通常是 app 模块下)的 build.gradle 中添加依赖:

dependencies {
    ...
    // 增加这行
    implementation 'com.tencent.qcloud:cosxml:5.5.4'
}

如果您的项目中使用 kotlin 开发,可以添加我们的 ktx 扩展包,提供了更加友好的 API:

dependencies {
    ...
    // 增加这行
    implementation 'com.tencent.qcloud:cosxml-ktx:5.5.0'
}

精简版 SDK

若您只使用上传、下载和复制等对象基础功能,同时对包体积有严格要求,也可使用精简版 SDK。

首先,在您项目级别的 build.gradle 文件中添加 bintray 的仓库地址:

allprojects {
 repositories {
     ...
     // 添加 maven 仓库
     maven {
         url "https://dl.bintray.com/tencentqcloudterminal/maven"
     }
 }
}

然后,在应用级别(通常是 app 模块下)的 build.gradle 中将依赖修改为 cosxml-lite

dependencies {
    ...
    // 增加这行
    implementation 'com.tencent.qcloud:cosxml-lite:5.5.4'
}

关闭 mta 上报功能

为了持续跟踪和优化 SDK 的质量,给您带来更好的使用体验,我们在 SDK 中引入了腾讯移动分析(mta)。

若是想关闭该功能,请在应用级别(通常是 app 模块下)的 build.gradle 中添加去掉 mta 的语句:

dependencies {
    ...
    implementation ('com.tencent.qcloud:cosxml:x.x.x'){
        // 增加这行
        exclude group:'com.tencent.qcloud', module: 'mtaUtils'
    }
}

方式二:手动集成

1. 下载归档文件

您可以通过 快速下载地址 下载最新的正式包,也可以在 SDK Releases 里面找到我们所有历史版本的正式包。

下载完成并解压后,您可以看到里面包含了数个 jaraar 包。下面是对它们的简单说明,请根据需要选择集成的包。

必选的库

  • cosxml:COS 协议实现
  • qcloud-foundation:基础库
  • bolts-tasks:第三方 Task 库
  • okhttp:第三方 Networking 库
  • okio:第三方 IO 库

可选的库

  • mtaUtils: mta 移动分析,用于改进 SDK
  • mid-sdk: mta 移动分析,用于改进 SDK
  • mta-android-sdk: mta 移动分析,用于改进 SDK
  • LogUtils: 日志模块,用于改进 SDK
  • quic:QUIC 协议,当您使用到 QUIC 协议来传输数据时需要

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 = "COS_SECRETID"; // 临时密钥 SecretId
        String tmpSecretKey = "COS_SECRETKEY"; // 临时密钥 SecretKey
        String sessionToken = "COS_SESSIONTOKEN"; // 临时密钥 Token
        long expiredTime = 1556183496L;//临时密钥有效截止时间戳,单位是秒

        //建议返回服务器时间作为签名的开始时间,避免由于用户手机本地时间偏差过大导致请求过期
        // 返回服务器时间作为签名的起始时间
        long startTime = 1556182000L; //临时密钥有效起始时间,单位是秒

        // 最后返回临时密钥信息对象
        return new SessionQCloudCredentials(tmpSecretId, tmpSecretKey,
                sessionToken, startTime, expiredTime);
    }
}

这里假设类名为 MySessionCredentialProvider。初始化一个实例,来给 SDK 提供密钥。

QCloudCredentialProvider myCredentialProvider = new MySessionCredentialProvider();

使用永久密钥进行本地调试

您可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄漏密钥的风险,请务必在上线前替换为临时密钥的方式。

String secretId = "COS_SECRETID"; //永久密钥 secretId
String secretKey = "COS_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);
说明:

关于存储桶不同地域的简称请参考 地域和访问域名

使用 ktx 包初始化 COS Service

如果您使用 ktx,初始化代码简化为:

val cos = cosService(context = application.applicationContext) {

    configuration {
        setRegion("ap-guangzhou")
        isHttps(true)
    }

    credentialProvider {
        lifecycleCredentialProvider {
            // fetch credential from backend
            // ...
            return@lifecycleCredentialProvider SessionQCloudCredentials(
                    "temp_secret_id",
                    "temp_secret_key",
                    "session_token",
                    1556183496
            )
        }
    }
}

第四步:访问 COS 服务

上传对象

SDK 支持上传本地文件、二进制数据、Uri 以及输入流。下面以上传本地文件为例。

// 初始化 TransferConfig,这里使用默认配置,如果需要定制,请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
        transferConfig);

String bucket = "examplebucket-1250000000"; //存储桶,格式:BucketName-APPID
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 cOSXMLUploadTaskResult =
                (COSXMLUploadTask.COSXMLUploadTaskResult) result;
    }

    @Override
    public void onFail(CosXmlRequest request,
                        CosXmlClientException clientException,
                        CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});
//设置任务状态回调, 可以查看任务过程
cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
    @Override
    public void onStateChanged(TransferState state) {
        // todo notify transfer state
    }
});

使用 ktx 包上传对象

如果您使用 ktx,请参考下面的上传示例代码:

// 这里使用了 viewModel 的 ktx 扩展
// viewModelScope 是 viewmodel 自带的 coroutine scope
viewModelScope.launch {
    val `object` = cosObject {
        bucket = cosBucket {
            service = cos
            name = "examplebucket-1250000000"
        }
        key = "exampleObject"
    }
    // 本地示例文件
    val sourceFile = File(appContext.externalCacheDir, "sourceFile")

    try {
        // upload 方法是 suspend function
        val result = `object`.upload(
            localFile = sourceFile,
            progressListener = { complete, target ->
                Log.d("cosxmlktx", "upload onProgress:" +
                                " $complete / $target")
            },
            transferStateListener = { state ->
                Log.d("cosxmlktx", "upload state is : $state")
            }
        )

    } catch (e : Exception ) {
        e.printStackTrace()
    }

}
说明:

  • 更多完整示例,请前往 GitHub 查看。
  • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

下载对象

// 高级下载接口支持断点续传,所以会在下载前先发起 HEAD 请求获取文件信息。
// 如果您使用的是临时密钥或者使用子账号访问,请确保权限列表中包含 HeadObject 的权限。

// 初始化 TransferConfig,这里使用默认配置,如果需要定制,请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
//初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
        transferConfig);

String bucket = "examplebucket-1250000000"; //存储桶,格式:BucketName-APPID
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 cOSXMLDownloadTaskResult =
                (COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
    }

    @Override
    public void onFail(CosXmlRequest request,
                        CosXmlClientException clientException,
                        CosXmlServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        } else {
            serviceException.printStackTrace();
        }
    }
});
//设置任务状态回调,可以查看任务过程
cosxmlDownloadTask.setTransferStateListener(new TransferStateListener() {
    @Override
    public void onStateChanged(TransferState state) {
        // todo notify transfer state
    }
});

使用 ktx 包下载对象

如果您使用 ktx,请参考下面的下载示例代码:

// 这里使用了 viewModel 的 ktx 扩展
// viewModelScope 是 viewmodel 自带的 coroutine scope
viewModelScope.launch {
    val `object` = cosObject {
        bucket = cosBucket {
            service = cos
            name = "examplebucket-1250000000"
        }
        key = "exampleObject"
    }

    try {
        // download 方法是 suspend function
        val result = `object`.download(
            context = appContext,
            destDirectory = appContext.externalCacheDir!!,
            progressListener = { complete, target ->
                Log.d("cosxmlktx", "download onProgress: " +
                        "$complete / $target")
            },
            transferStateListener = { state ->
                Log.d("cosxmlktx", "download state is : $state")
            }
        )

    } catch (e : Exception ) {
        e.printStackTrace()
    }

}
说明:

  • 更多完整示例,请前往 GitHub 查看。
  • 高级下载接口支持断点续传,所以会在下载前先发起 HEAD 请求获取文件信息。如果您使用的是临时密钥或者使用子账号访问,请确保权限列表中包含 HeadObject 的权限。
目录