tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    快速入门

    最后更新时间：2024-01-04 15:52:02
    下载PDF

      相关资源

      SDK 源码下载请参见 XML Android SDK。
      示例 Demo 请参见 XML Android SDK Demo。
      SDK 接口与参数文档请参见 SDK API 参考。
      SDK 文档中的所有示例代码请参见 SDK 代码示例。
      SDK 更新日志请参见 ChangeLog。
      SDK 常见问题请参见：Android SDK 常见问题。
      说明
      如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误，请先将 XML 版本 SDK 升级到最新版再重试。

      准备工作

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

      第一步：安装 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.+'
      }

      关闭腾讯灯塔上报功能

      为了持续跟踪和优化 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）以上，您需要在运行时动态申请存储权限。

      第三步：开始使用

      注意
      建议用户 使用临时密钥 调用 SDK，通过临时授权的方式进一步提高 SDK 使用的安全性。申请临时密钥时，请遵循 最小权限指引原则，防止泄漏目标存储桶或对象之外的资源。
      如果您一定要使用永久密钥，建议遵循 最小权限指引原则 对永久密钥的权限范围进行限制。

      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);

      使用服务端计算的签名对请求授权

      实现一个 QCloudSelfSigner 的子类，实现获取服务端签名并加入请求授权。
      QCloudSelfSigner myQCloudSelfSigner = new QCloudSelfSigner() {
          /**
           * 对请求进行签名
           *
           * @param request 需要签名的请求
           * @throws QCloudClientException 客户端异常
           */
          @Override
          public void sign(QCloudHttpRequest request) throws QCloudClientException {
              // 1. 把 request 的请求参数传给服务端计算签名
              String auth = "get auth from server";
              // 2. 给请求添加签名
              request.addHeader(HttpConstants.Header.AUTHORIZATION, auth);
          }
      });

      2. 初始化 COS Service

      使用您提供密钥的实例 myCredentialProvider 或 服务端签名授权实例 myQCloudSelfSigner，初始化一个 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 Service，获取实例
      CosXmlService cosXmlService = new CosXmlService(context,
          serviceConfig, myQCloudSelfSigner);
      说明
      关于存储桶不同地域的简称请参考 地域和访问域名。

      第四步：访问 COS 服务

      上传对象

      SDK 支持上传本地文件、二进制数据、Uri 以及输入流。下面以上传本地文件为例：
      // 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
      TransferConfig transferConfig = new TransferConfig.Builder().build();
      // 初始化 TransferManager
      TransferManager transferManager = new TransferManager(cosXmlService,
              transferConfig);
      
      // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.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);
      
      //设置初始化分块上传回调(5.9.7版本以及后续版本支持)
      cosxmlUploadTask.setInitMultipleUploadListener(new InitMultipleUploadListener() {
          @Override
          public void onSuccess(InitiateMultipartUpload initiateMultipartUpload) {
              //用于下次续传上传的 uploadId
              String uploadId = initiateMultipartUpload.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
          }
      });
      说明
      更多完整示例，请前往 GitHub 查看。
      上传之后，您可以用同样的 Key 生成文件下载链接，具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限，那么下载链接只有一定的有效期。

      下载对象

      // 高级下载接口支持断点续传，所以会在下载前先发起 HEAD 请求获取文件信息。
      // 如果您使用的是临时密钥或者使用子账号访问，请确保权限列表中包含 HeadObject 的权限。
      
      // 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
      TransferConfig transferConfig = new TransferConfig.Builder().build();
      //初始化 TransferManager
      TransferManager transferManager = new TransferManager(cosXmlService,
              transferConfig);
      
      // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.tencentcloud.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 的权限。
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款