tencent cloud

文档反馈

快速入门

最后更新时间:2022-05-16 15:04:48

    下载与安装

    相关资源

    说明:

    • 为了避免不必要的繁琐代码排查与程序定位问题,如果您初次使用 COS 或者数据量不大,推荐使用更加友好、图形化界面的 控制台COSBrowser,或者可批量操作的命令行工具 COSCLI
    • 如果您在使用 XML 版本 SDK 时遇到函数或方法不存在等错误,请先将 XML 版本 SDK 升级到最新版再重试。

    环境依赖

    说明:

    • 关于文章中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息
    • COS Java SDK 中的常见类所在包分别为:
    • 客户端配置相关类在 com.qcloud.cos.* 包下。
    • 权限相关类在 com.qcloud.cos.auth.* 子包下。
    • 异常相关类在 com.qcloud.cos.exception.* 子包下。
    • 请求相关类在 com.qcloud.cos.model.* 子包下。
    • 地域相关类在 com.qcloud.cos.region.* 子包下。
    • 高级 API 接口在 com.qcloud.cos.transfer.* 子包下。

    安装 SDK

    用户可以通过 maven 和源码两种方式安装 Java SDK:

    • maven 安装
      在 maven 工程的 pom.xml 文件中添加相关依赖,内容如下:

      <dependency>
          <groupId>com.qcloud</groupId>
          <artifactId>cos_api</artifactId>
          <version>5.6.54</version>
      </dependency>
      
    • 源码安装
      从 Github XML Java SDK快速下载地址 下载源码,通过 maven 导入。例如 eclipse,依次选择 File > Import > maven > Existing Maven Projects

    卸载 SDK

    通过删除 pom 依赖或源码即可卸载 SDK。

    开始使用

    正式使用前,先别急着书写第一行代码,请先花两分钟做下面的测试,确保发送的请求能够到达 COS 服务,这可以帮助您确认是否遇到了大部分用户在使用 Java SDK 时碰到的问题。
    下面测试中假设您尝试访问广州地域的 COS 服务。

    使用 ping 测试

    [root@VM_centos /data/home/]# ping cos.ap-guangzhou.myqcloud.com
    PING cos.ap-guangzhou.myqcloud.com (9.*.*.*) xx(xx) bytes of data.
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=1 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=2 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=3 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=4 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=5 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=6 ttl=xx time=0.xxx ms
    64 bytes from 9.*.*.* (9.*.*.*): icmp_seq=7 ttl=xx time=0.xxx ms
    ^C
    --- cos.ap-guangzhou.myqcloud.com ping statistics ---
    x packets transmitted, x received, 0% packet loss, time xxxms
    rtt min/avg/max/mdev = 0.xxx/0.xxx/0.xxx/0.xxx ms 
    

    如果显示类似上面结果,则基本网络连通与名字服务都是正常的。如果返回其他异常结果,请优先排查环境网络问题或者联系本地网络管理员,确认全部正常后,再继续下一步。
    如果是在 Windows 下,也可以单击开始 (或快捷键:Win+R)> 运行 (输入 cmd)> 确定(或按 Enter 键),输入命令ping cos.ap-guangzhou.myqcloud.com并回车进行测试。

    使用 curl 测试

    如果使用 HTTP 访问:

    [root@VM_centos /data/home/]# curl http://cos.ap-guangzhou.myqcloud.com -v
    * About to connect() to cos.ap-guangzhou.myqcloud.com port 80 (#0)
    *   Trying 9.*.*.*...
    * Connected to cos.ap-guangzhou.myqcloud.com (9.*.*.*) port 80 (#0)
    > GET / HTTP/1.1
    > User-Agent: curl/*.*.0
    > Host: cos.ap-guangzhou.myqcloud.com
    > Accept: */*
    > 
    < HTTP/1.1 403 Forbidden
    < Content-Type: application/xml
    < Content-Length: XXX
    < Connection: keep-alive
    < Date: XXX XXX GMT
    < Server: tencent-cos
    < x-cos-request-id: NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****
    < 
    <?xml version='1.0' encoding='utf-8' ?>
    <Error>
           <Code>AccessDenied</Code>
           <Message>Check auth failure because signture empty.</Message>
           <ServerTime>XXX XXX</ServerTime>
           <Resource>cos.ap-guangzhou.myqcloud.com/</Resource>
           <RequestId>NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****==</RequestId>    
    </Error>
    * Connection #0 to host cos.ap-guangzhou.myqcloud.com left intact
    

    如果使用 HTTPS 访问:

    [root@VM_centos /data/home/]# curl https://cos.ap-guangzhou.myqcloud.com -vk
    * About to connect() to cos.ap-guangzhou.myqcloud.com port 443 (#0)
    *   Trying 9.*.*.*...
    * Connected to cos.ap-guangzhou.myqcloud.com (9.*.*.*) port 443 (#0)
    * Initializing NSS with certpath: XXXX
    * skipping SSL peer certificate verification
    * SSL connection using ******
    * Server certificate:
    *       subject: CN=*.*.*.
    *       start date: XXX XXX GMT
    *       expire date: XXX XXX GMT
    *       common name: *.cos.ap-guangzhou.myqcloud.com
    *       issuer: XXX
    > GET / HTTP/1.1
    > User-Agent: curl/*.*.0
    > Host: cos.ap-guangzhou.myqcloud.com
    > Accept: */*
    > 
    < HTTP/1.1 403 Forbidden
    < Content-Type: application/xml
    < Content-Length: XXX
    < Connection: keep-alive
    < Date: XXX XXX GMT
    < Server: tencent-cos
    < x-cos-request-id: NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****
    < 
    <?xml version='1.0' encoding='utf-8' ?>
    <Error>
           <Code>AccessDenied</Code>
           <Message>Check auth failure because signture empty.</Message>
           <ServerTime>XXX XXX</ServerTime>
           <Resource>cos.ap-guangzhou.myqcloud.com/</Resource>
           <RequestId>NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****</RequestId>        
    </Error>
    * Connection #0 to host cos.ap-guangzhou.myqcloud.com left intact
    

    如果显示类似上面结果,则说明端口连接正常。如果返回其他异常结果,请优先排查环境网络问题或者联系本地网络管理员,确认全部正常后,再继续下一步。
    在 Windows 环境下,某些版本可能需要额外安装 curl 工具才能测试。

    下面为您介绍如何使用 COS Java SDK 完成一个基础操作,例如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。对于示例中出现的类,在 IDE 中,您可以单击该类,查看该类的所有字段和函数定义,类中有较为详细的注释。

    导入类名

    COS Java SDK 的包名为com.qcloud.cos.*,您可以通过 Eclipse 或者 Intellij 等 IDE 工具,导入程序运行所需要的类。

    初始化客户端

    在执行任何和 COS 服务相关请求之前,都需要先生成 COSClient 类的对象, COSClient 是调用 COS API 接口的对象。

    注意:

    COSClient 是线程安全的类,允许多线程访问同一实例。因为实例内部维持了一个连接池,创建多个实例可能导致程序资源耗尽,请确保程序生命周期内实例只有一个,并在不再需要使用时,调用 shutdown 方法将其关闭。如果需要新建实例,请先将之前的实例关闭。

    若您使用永久密钥初始化 COSClient,可以先在访问管理控制台中的 API 密钥管理 页面获取 APPId、SecretId、SecretKey,使用永久密钥适用于大部分的应用场景,参考示例如下:

    // 1 初始化用户身份信息(secretId, secretKey)。
    // SECRETID和SECRETKEY请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
    String secretId = "SECRETID";
    String secretKey = "SECRETKEY";
    COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
    // 2 设置 bucket 的地域, COS 地域的简称请参照 https://intl.cloud.tencent.com/document/product/436/6224
    // clientConfig 中包含了设置 region, https(默认 http), 超时, 代理等 set 方法, 使用可参见源码或者常见问题 Java SDK 部分。
    Region region = new Region("COS_REGION");
    ClientConfig clientConfig = new ClientConfig(region);
    // 这里建议设置使用 https 协议
    // 从 5.6.54 版本开始,默认使用了 https
    clientConfig.setHttpProtocol(HttpProtocol.https);
    // 3 生成 cos 客户端。
    COSClient cosClient = new COSClient(cred, clientConfig);
    

    您也可以使用临时密钥初始化 COSClient,临时密钥生成和使用可参见 临时密钥生成及使用指引,参考示例如下:

    // 1 传入获取到的临时密钥 (tmpSecretId, tmpSecretKey, sessionToken)
    String tmpSecretId = "SECRETID";
    String tmpSecretKey = "SECRETKEY";
    String sessionToken = "TOKEN";
    BasicSessionCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
    // 2 设置 bucket 的地域, COS 地域的简称请参阅 https://intl.cloud.tencent.com/document/product/436/6224
    // clientConfig 中包含了设置 region, https(默认 http), 超时, 代理等 set 方法, 使用可参阅源码或者常见问题 Java SDK 部分
    Region region = new Region("COS_REGION");
    ClientConfig clientConfig = new ClientConfig(region);
    // 3 生成 cos 客户端
    COSClient cosClient = new COSClient(cred, clientConfig);
    

    ClientConfig 类为配置信息类,主要的成员如下:

    成员名 设置方法 描述 类型
    region 构造函数或 set 方法 存储桶所在的地域,COS 地域的简称请参见 地域和访问域名 文档 Region
    httpProtocol set 方法 请求所使用的协议,默认使用 HTTPS 协议与 COS 交互 HttpProtocol
    signExpired set 方法 请求签名的有效时间,单位:秒,默认为3600s long
    connectionTimeout set 方法 连接 COS 服务的超时时间,单位:毫秒,默认为30000ms int
    socketTimeout set 方法 客户端读取数据的超时时间,单位:毫秒,默认为30000ms int
    httpProxyIp set 方法 代理服务器的 IP String
    httpProxyPort set 方法 代理服务器的端口 int

    创建存储桶

    用户确定地域和存储桶名称后,参考如下示例创建存储桶:

    String bucket = "examplebucket-1250000000"; //存储桶名称,格式:BucketName-APPID
    CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
    // 设置 bucket 的权限为 Private(私有读写)、其他可选有 PublicRead(公有读私有写)、PublicReadWrite(公有读写)
    createBucketRequest.setCannedAcl(CannedAccessControlList.Private);
    try{
       Bucket bucketResult = cosClient.createBucket(createBucketRequest);
    } catch (CosServiceException serverException) {
       serverException.printStackTrace();
    } catch (CosClientException clientException) {
       clientException.printStackTrace();
    }
    

    查询存储桶列表

    查询用户的存储桶列表,参考示例如下:

    List<Bucket> buckets = cosClient.listBuckets();
    for (Bucket bucketElement : buckets) {
       String bucketName = bucketElement.getName();
       String bucketLocation = bucketElement.getLocation();
    }
    

    上传对象

    将本地文件或者已知长度的输入流内容上传到 COS,适用于20M以下图片类小文件上传,最大支持上传不超过5GB文件。5GB以上的文件必须使用分块上传或高级 API 接口上传。

    说明:

    高级 API 接口在 com.qcloud.cos.transfer.* 子包下。

    • 若本地文件大部分在20M以上,建议您参考使用高级 API 接口进行上传。
    • 若 COS 上已存在同样 Key 的对象,上传时则会覆盖旧的对象。
    • 若要创建目录对象,请参见 SDK 如何创建目录
    • 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/images/picture.jpg 中,对象键为 images/picture.jpg,详情请参见 对象键 的说明。

    上传不超过5GB的文件,参考示例如下:

    // 指定要上传的文件
    File localFile = new File(localFilePath);
    // 指定文件将要存放的存储桶
    String bucketName = "examplebucket-1250000000";
    // 指定文件上传到 COS 上的路径,即对象键。例如对象键为folder/picture.jpg,则表示将文件 picture.jpg 上传到 folder 路径下
    String key = "exampleobject";
    PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
    PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
    

    查询对象列表

    查询存储桶中对象列表,参考示例如下:

    // Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
    // 设置bucket名称
    listObjectsRequest.setBucketName(bucketName);
    // prefix表示列出的object的key以prefix开始
    listObjectsRequest.setPrefix("images/");
    // deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object
    listObjectsRequest.setDelimiter("/");
    // 设置最大遍历出多少个对象, 一次listobject最大支持1000
    listObjectsRequest.setMaxKeys(1000);
    ObjectListing objectListing = null;
    do {
       try {
           objectListing = cosClient.listObjects(listObjectsRequest);
       } catch (CosServiceException e) {
           e.printStackTrace();
           return;
       } catch (CosClientException e) {
           e.printStackTrace();
           return;
       }
       // common prefix表示表示被delimiter截断的路径, 如delimter设置为/, common prefix则表示所有子目录的路径
       List<String> commonPrefixs = objectListing.getCommonPrefixes();
        // object summary表示所有列出的object列表
       List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();
       for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {
           // 文件的路径key
           String key = cosObjectSummary.getKey();
           // 文件的etag
           String etag = cosObjectSummary.getETag();
           // 文件的长度
           long fileSize = cosObjectSummary.getSize();
           // 文件的存储类型
           String storageClasses = cosObjectSummary.getStorageClass();
       }
        String nextMarker = objectListing.getNextMarker();
       listObjectsRequest.setMarker(nextMarker);
    } while (objectListing.isTruncated());
    

    下载对象

    上传对象后,您可以用同样的 key,调用 GetObject 接口将对象下载到本地,也可以生成预签名链接(下载请指定 method 为 GET,详情请参见 预签名 URL),分享到其他终端来进行下载。但如果您的文件设置了私有读权限,那么请注意预签名链接的有效期。
    将文件下载到本地指定路径,参考示例如下:

    // Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 指定文件在 COS 上的路径,即对象键。例如对象键为folder/picture.jpg,则表示下载的文件 picture.jpg 在 folder 路径下
    String key = "exampleobject";
    // 方法1 获取下载输入流
    GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
    COSObject cosObject = cosClient.getObject(getObjectRequest);
    COSObjectInputStream cosObjectInput = cosObject.getObjectContent();
    // 下载对象的 CRC64
    String crc64Ecma = cosObject.getObjectMetadata().getCrc64Ecma();
    // 关闭输入流
    cosObjectInput.close();
    // 方法2 下载文件到本地的路径,例如 D 盘的某个目录
    String outputFilePath = "exampleobject";
    File downFile = new File(outputFilePath);
    getObjectRequest = new GetObjectRequest(bucketName, key);
    ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);
    

    删除对象

    删除 COS 上指定路径的对象,代码如下:

    // Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 指定被删除的文件在 COS 上的路径,即对象键。例如对象键为folder/picture.jpg,则表示删除位于 folder 路径下的文件 picture.jpg
    String key = "exampleobject";
    cosClient.deleteObject(bucketName, key);
    

    默认请求重试策略

    使用 SDK 生成的 cosClient 发起的请求,默认已经对响应错误的请求进行了重试。重试规则如下:

    • 重试的次数:默认值为 3,可以通过 clientConfig.setMaxErrorRetry 进行设置。
      如果设置为 0,则所有类型的错误请求都不进行重试。
    • 重试的错误类型:客户端异常中所有的报 IOException 的错误。服务端异常中状态码为 500, 502, 503 504 的错误。

    用户也可以根据自己的需求,设置重试策略。代码如下:

    设置重试次数:

    Region region = new Region("COS_REGION");
    ClientConfig clientConfig = new ClientConfig(region);
    // 设置最大重试次数为 4 次
    clientConfig.setMaxErrorRetry = 4;
    

    设置重试策略:

    // 自定义重试策略
    public class OnlyIOExceptionRetryPolicy extends RetryPolicy {
       @Override
       public <X extends CosServiceRequest> boolean shouldRetry(CosHttpRequest<X> request,
               HttpResponse response,
               Exception exception,
               int retryIndex) {
           // 如果是客户端的 IOException 异常则重试,否则不重试
           if (exception.getCause() instanceof IOException) {
               return true;
           }
           return false;
       }
    }
    Region region = new Region("COS_REGION");
    ClientConfig clientConfig = new ClientConfig(region);
    RetryPolicy myRetryPolicy = new OnlyIOExceptionRetryPolicy();
    // 设置自定义的重试策略
    clientConfig.setRetryPolicy(myRetryPolicy);
    

    关闭客户端

    关闭 cosClient,并释放 HTTP 连接的后台管理线程,代码如下:

    // 关闭客户端(关闭后台线程)
    cosClient.shutdown();
    

    常见问题

    您在使用过程中可能会碰到的一些常见问题,相关的解决办法可参见 Java SDK 常见问题

    联系我们

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

    技术支持

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

    7x24 电话支持