相关资源

• SDK 源码请参见 XML Android SDK。
• 示例 Demo 请参见 XML Android SDK Demo。
• SDK 接口与参数文档请参见 SDK API 参考。
• SDK 文档中的所有示例代码请参见 SDK 代码示例。
• SDK 更新日志请参见 ChangeLog。

准备工作

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

第一步：安装 SDK

方式一：自动集成（推荐）

标准版 SDK

在应用级别（通常是 app 模块下）的 build.gradle 中添加依赖：

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

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

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

精简版 SDK

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

说明：

接入精简版 SDK 时，CosXmlService 需要使用 CosXmlSimpleService 来替代。

首先，在您项目级别的 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.5'
}

关闭 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 里面找到我们所有历史版本的正式包。

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

必选的库

• 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 的权限。