升级到 XML Android SDK

如果您细心对比过 JSON Android SDK 和 XML Android SDK 的文档，您会发现并不是一个简单的增量更新。XML Android SDK 不仅在架构、可用性和安全性上有了非常大的提升，而且在易用性、健壮性和传输性能上也做了非常大的改进。如果您想要升级到 XML Android SDK，请参考下面的指引，一步步完成 SDK 的升级工作。

功能对比

下表列出了 JSON Android SDK 和 XML Android SDK 的主要功能对比：

升级步骤

请按照以下步骤升级 Android SDK。

1. 更新 Android SDK

COS XML Android SDK Android SDK 发布在 MavenCentral 的 maven 包管理平台，推荐您使用自动集成方式进行更新。

在应用的根目录下的 build.gradle 中添加依赖，代码如下：

dependencies {
...
  // 增加这行
  compile 'com.qcloud.cos:cos-android:5.6.+'
}

当然，您也可以继续选择手动 jar 包依赖，您可以在这里 COS XML Android SDK-release 下载所有的 jar 包。

2. 更改 SDK 鉴权方式

在 JSON Android SDK 中您需要自己在后台计算好签名，再返回客户端使用。而在 XML SDK 使用了新的鉴权算法，在 XML Android SDK 中，强烈建议您后台接入我们的临时密钥（STS）方案。该方案不需要您了解签名计算过程，只需要在服务器端接入 CAM，将拿到的临时密钥返回到客户端，并设置到 SDK 中，SDK 会负责管理密钥和计算签名。临时密钥在一段时间后会自动失效，而永久密钥不会泄露。
您还可以按照不同的粒度来控制访问权限。具体的步骤请参考 移动应用直传实践 以及 临时密钥生成及使用指引。

如果您仍然采用后台手动计算签名，再返回客户端使用的方式，请注意我们的签名算法发生了改变。签名不再区分单次和多次签名，而是通过设置签名的有效期来保证安全性。请参考 XML 请求签名 文档更新您签名的实现。

3. 更改 SDK 初始化

在 XML Android SDK 中，我们的初始化接口发生了一些变化：

• 为了区分，CosXmlServiceConfig 代替了 COSClientConfig，CosXmlService 代替了 COSClient，但他们的作用相同。
• 您需要在初始化时实例化一个密钥提供者 QCloudCredentialProvider，用于提供一个有效的密钥，建议使用临时密钥。

JSON SDK 的初始化方式如下：

//创建COSClientConfig对象，根据需要修改默认的配置参数
COSClientConfig config = new COSClientConfig();
//设置地域
config.setEndPoint(COSEndPoint.COS_GZ);
Context context = getApplicationContext()；
String appid =  "腾讯云注册的appid";
String peristenceId = "持久化Id";
//创建COSlient对象，实现对象存储的操作
COSClient cos = new COSClient(context,appid,config,peristenceId);

XML SDK 的初始化方式如下：

String region = "COS_REGION";
CosXmlServiceConfig serviceConfig = new CosXmlServiceConfig.Builder()
       .setRegion(region)
       .isHttps(true) // 使用 HTTPS 请求，默认为 HTTP 请求
       .builder();
URL url = null;
try {
   // URL 是后台临时密钥服务的地址，如何搭建服务请参考（https://cloud.tencent.com/document/product/436/14048）
   url = new URL("https://your_auth_server_url");
} catch (MalformedURLException e) {
   e.printStackTrace();
   return;
}
/**
* 初始化 {@link QCloudCredentialProvider} 对象，来给 SDK 提供临时密钥
*/
QCloudCredentialProvider credentialProvider = new SessionCredentialProvider(new HttpRequest.Builder<String>()
       .url(url)
       .method("GET")
       .build());
CosXmlService cosXmlService = new CosXmlService(context, serviceConfig, credentialProvider);

4. 更改存储桶名称和可用区域简称

XML SDK 的存储桶名称和可用区域简称与 JSON SDK 的不同，需要您进行相应的更改。

存储桶 Bucket

XML Android SDK 存储桶名称由两部分组成：用户自定义字符串 和 APPID，两者以中划线“-”相连。例如 examplebucket-1250000000，其中 examplebucket 为用户自定义字符串，1250000000为 APPID。

说明：

APPID 是腾讯云账户的账户标识之一，用于关联云资源。在用户成功申请腾讯云账户后，系统自动为用户分配一个 APPID。可通过 账号信息 控制台查看 APPID。

在设置 Bucket 时，请参考下面的示例代码：

String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject.doc";
String srcPath = Environment.getExternalStorageDirectory().getPath() + "/exampleobject.doc";
//上传文件
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath, srcPath, uploadId);

存储桶可用区域简称 Region

XML Android SDK 的存储桶可用区域简称发生了变化，下列表格列出了不同区域在 JSON Android SDK 和 XML Android SDK 中的对应关系：

在初始化时，请将存储桶所在区域简称设置到 CosXmlServiceConfig 中：

String appid = "1250000000";
String region = "ap-guangzhou"; 
CosXmlServiceConfig serviceConfig = new CosXmlServiceConfig.Builder()
     .setAppidAndRegion(appid, region)
     .builder();

5. 更改 API

升级到 XML SDK 之后，一些操作的 API 发生了变化，请您根据实际需求进行相应的更改。我们同时做了封装让 SDK 更加易用，具体请参考我们的示例和 快速入门 文档。

API 变化有以下三点：

（1）没有单独的目录接口

在 XML SDK 中，不再提供单独的目录接口。对象存储中本身是没有文件夹和目录的概念的，对象存储不会因为上传对象 project/a.txt 而创建一个 project 文件夹。
为了满足用户使用习惯，对象存储在控制台、COS browser 等图形化工具中模拟了「 文件夹」或「 目录」的展示方式，具体实现是通过创建一个键值为project/，内容为空的对象，展示方式上模拟了传统文件夹。

例如：上传对象project/doc/a.txt ，分隔符/会模拟「文件夹」的展示方式，于是可以看到控制台上出现「 文件夹」project 和 doc，其中 doc 是 project 下一级「 文件夹」，并包含了 a.txt 。

因此，如果您的应用场景只是上传文件，可以直接上传即可，不需要先创建文件夹。

如果您的使用场景里面有文件夹的概念，需要提供创建文件夹的功能，您可以上传一个路径以 '/' 结尾的 0KB 文件。这样在您调用 GetBucket 接口时，就可以将这样的文件当做文件夹。

（2）TransferManager

在 XML SDK 中，我们封装了上传、下载和复制操作，命名为TransferManager，同时对 API 设计和传输性能都做了优化，建议您直接使用。TransferManager的主要特性有：

• 支持上传下载过程的暂停和恢复。
• 支持根据文件大小智能选择简单上传还是分块上传，您可以设置该判断临界。
• 支持任务状态的监听。

使用TransferManager上传的示例代码：

// 初始化 TransferConfig
TransferConfig transferConfig = new TransferConfig.Builder().build();
/*若有特殊要求，则可以如下进行初始化定制。例如限定当对象 >= 2M 时，启用分块上传，且分块上传的分块大小为1M，当源对象大于5M时启用分块复制，且分块复制的大小为5M。*/
transferConfig = new TransferConfig.Builder()
       .setDividsionForCopy(5 * 1024 * 1024) // 是否启用分块复制的最小对象大小
       .setSliceSizeForCopy(5 * 1024 * 1024) // 分块复制时的分块大小
       .setDivisionForUpload(2 * 1024 * 1024) // 是否启用分块上传的最小对象大小
       .setSliceSizeForUpload(1024 * 1024) // 分块上传时的分块大小
       .build();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService, transferConfig);
String bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
String srcPath = new File(context.getExternalCacheDir(), "exampleobject").toString(); //本地文件的绝对路径
String uploadId = null; //若存在初始化分块上传的 UploadId，则赋值对应的 uploadId 值用于续传；否则，赋值 null
// 上传对象
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath, srcPath, uploadId);
/**
* 若是上传字节数组，则可调用 TransferManager 的 upload(string, string, byte[]) 方法实现;
* byte[] bytes = "this is a test".getBytes(Charset.forName("UTF-8"));
* cosxmlUploadTask = transferManager.upload(bucket, cosPath, bytes);
*/
/**
* 若是上传字节流，则可调用 TransferManager 的 upload(String, String, InputStream) 方法实现；
* InputStream inputStream = new ByteArrayInputStream("this is a test".getBytes(Charset.forName("UTF-8")));
* cosxmlUploadTask = transferManager.upload(bucket, cosPath, inputStream);
*/
//设置上传进度回调
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 exception, CosXmlServiceException serviceException) {
       // todo Upload failed because of CosXmlClientException or CosXmlServiceException...
   }
});
//设置任务状态回调, 可以查看任务过程
cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
   @Override
   public void onStateChanged(TransferState state) {
       // todo notify transfer state
   }
});
/**
若有特殊要求，则可以如下操作：
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, srcPath);
putObjectRequest.setRegion(region); //设置存储桶所在的地域
putObjectRequest.setNeedMD5(true); //是否启用 Md5 校验
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(putObjectRequest, uploadId);
*/
//取消上传
cosxmlUploadTask.cancel();

//暂停上传
cosxmlUploadTask.pause();
//恢复上传
cosxmlUploadTask.resume();

（3）新增 API

XML Android SDK 新增 API，您可根据需求进行调用。包括：

• 存储桶的操作，如 PutBucketRequest、GetBucketRequest、ListBucketRequest 等。
• 存储桶 ACL 的操作，如 PutBucketACLRequest、GetBucketACLRequest 等。
• 存储桶生命周期的操作，如 PutBucketLifecycleRequest、GetBucketLifecycleRequest 等。

具体请参考我们的 Android SDK 快速入门 文档。