tencent cloud

文档反馈

生成预签名 URL

最后更新时间:2022-08-30 16:53:11

    简介

    本文档提供关于生成对象预签名链接的示例代码。

    关于使用预签名 url 上传的说明详见文档 预签名授权上传, 使用预签名 url 下载的说明详见文档 预签名授权下载

    说明:

    • 建议用户 使用临时密钥 生成预签名,通过临时授权的方式进一步提高预签名上传、下载等请求的安全性。申请临时密钥时,请遵循 最小权限指引原则,防止泄漏目标存储桶或对象之外的资源。
    • 如果您一定要使用永久密钥来生成预签名,建议永久密钥的权限范围仅限于上传或下载操作,以规避风险。
    • 获取签名/预签名函数,默认签入 Header Host;您也可以选择不签入 Header Host,但可能导致请求失败或安全漏洞。

    简单操作

    简单操作由 COSClient 类型发起请求,使用简单操作之前必须先创建一个 COSClient 实例。

    COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。

    创建 COSClient

    调用 COS 的接口之前,必须先创建一个 COSClient 的实例。

    // 创建 COSClient 实例,这个实例用来后续调用请求
    COSClient createCOSClient() {
      // 设置用户身份信息。
      // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.tencentcloud.com/cam/capi 进行查看和管理
      String secretId = "SECRETID";
      String secretKey = "SECRETKEY";
      COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
       // ClientConfig 中包含了后续请求 COS 的客户端设置:
      ClientConfig clientConfig = new ClientConfig();
       // 设置 bucket 的地域
      // COS_REGION 请参照 https://www.tencentcloud.com/document/product/436/6224
      clientConfig.setRegion(new Region("COS_REGION"));
       // 设置请求协议, http 或者 https
      // 5.6.53 及更低的版本,建议设置使用 https 协议
      // 5.6.54 及更高版本,默认使用了 https
      clientConfig.setHttpProtocol(HttpProtocol.https);
       // 以下的设置,是可选的:
       // 设置 socket 读取超时,默认 30s
      clientConfig.setSocketTimeout(30*1000);
      // 设置建立连接超时,默认 30s
      clientConfig.setConnectionTimeout(30*1000);
       // 如果需要的话,设置 http 代理,ip 以及 port
      clientConfig.setHttpProxyIp("httpProxyIp");
      clientConfig.setHttpProxyPort(80);
       // 生成 cos 客户端。
      return new COSClient(cred, clientConfig);
    }
    

    使用临时密钥创建 COSClient

    如果要使用临时密钥请求 COS,则需要用临时密钥创建 COSClient。
    本 SDK 并不能生成临时密钥,而需要使用额外的操作来生成,参考 临时密钥生成

    // 创建 COSClient 实例,这个实例用来后续调用请求
    COSClient createCOSClient() {
      // 这里需要已经获取到临时密钥的结果。
      // 临时密钥的生成参考 https://www.tencentcloud.com/document/product/436/14048#cos-sts-sdk
      String tmpSecretId = "TMPSECRETID";
      String tmpSecretKey = "TMPSECRETKEY";
      String sessionToken = "SESSIONTOKEN";
       COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
       // ClientConfig 中包含了后续请求 COS 的客户端设置:
      ClientConfig clientConfig = new ClientConfig();
       // 设置 bucket 的地域
      // COS_REGION 请参照 https://www.tencentcloud.com/document/product/436/6224
      clientConfig.setRegion(new Region("COS_REGION"));
       // 设置请求协议, http 或者 https
      // 5.6.53 及更低的版本,建议设置使用 https 协议
      // 5.6.54 及更高版本,默认使用了 https
      clientConfig.setHttpProtocol(HttpProtocol.https);
       // 以下的设置,是可选的:
       // 设置 socket 读取超时,默认 30s
      clientConfig.setSocketTimeout(30*1000);
      // 设置建立连接超时,默认 30s
      clientConfig.setConnectionTimeout(30*1000);
       // 如果需要的话,设置 http 代理,ip 以及 port
      clientConfig.setHttpProxyIp("httpProxyIp");
      clientConfig.setHttpProxyPort(80);
       // 生成 cos 客户端。
      return new COSClient(cred, clientConfig);
    }
    

    生成预签名 URL

    方法原型

    public URL generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethodName method, Map<String, String> headers, Map<String, String> params, Boolean signPrefixMode, Boolean signHost) throws CosClientException
    
    

    请求示例

    // 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
    // 详细代码参见本页:简单操作 -> 创建 COSClient
    COSClient cosClient = createCOSClient();
    // 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://www.tencentcloud.com/document/product/436/13324)
    String key = "exampleobject";
    // 设置签名过期时间(可选), 若未进行设置则默认使用 ClientConfig 中的签名过期时间(1小时)
    // 这里设置签名在半个小时后过期
    Date expirationDate = new Date(System.currentTimeMillis() + 30 * 60 * 1000);
    // 填写本次请求的参数,需与实际请求相同,能够防止用户篡改此签名的 HTTP 请求的参数 
    Map<String, String> params = new HashMap<String, String>();
    params.put("param1", "value1");
    // 填写本次请求的头部,需与实际请求相同,能够防止用户篡改此签名的 HTTP 请求的头部
    Map<String, String> headers = new HashMap<String, String>();
    headers.put("header1", "value1");
    // 请求的 HTTP 方法,上传请求用 PUT,下载请求用 GET,删除请求用 DELETE
    HttpMethodName method = HttpMethodName.GET;
    URL url = cosClient.generatePresignedUrl(bucketName, key, expirationDate, method, headers, params);
    System.out.println(url.toString());
    // 确认本进程不再使用 cosClient 实例之后,关闭之
    cosClient.shutdown();
    

    参数说明

    参数名称 描述 类型 是否必填
    method HTTP 方法,可选:GET、POST、PUT、DELETE、HEAD HttpMethodName
    bucketName 存储桶名称,存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范 String
    key 对象键(Key)是对象在存储桶中的唯一标识,详情请参见 对象键 String
    expiration 签名过期的时间,可以设置任意一个未来的时间,不设置则默认是1小时之后过期 Date
    headers 签名头部 Map<String, String>
    params 签名参数 Map<String, String>
    signPrefixMode 是否以 sign 参数指定签名(不推荐),默认 false boolean
    signHost 是否签入 Host 头部(推荐),默认 true boolean

    生成覆盖返回头部的预签名下载 URL

    方法原型

    public URL generatePresignedUrl(GeneratePresignedUrlRequest req, boolean signHost) throws CosClientException
    
    

    请求示例

    // 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
    // 详细代码参见本页:简单操作 -> 创建 COSClient
    COSClient cosClient = createCOSClient();
    // 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://www.tencentcloud.com/document/product/436/13324)
    String key = "exampleobject";
    GeneratePresignedUrlRequest req =
          new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);
    // 设置下载时返回的 http 头
    ResponseHeaderOverrides responseHeaders = new ResponseHeaderOverrides();
    String responseContentType = "image/x-icon";
    String responseContentLanguage = "zh-CN";
    // 设置返回头部里包含文件名信息
    String responseContentDispositon = "filename=\"exampleobject\"";
    String responseCacheControl = "no-cache";
    String cacheExpireStr =
          DateUtils.formatRFC822Date(new Date(System.currentTimeMillis() + 24L * 3600L * 1000L));
    responseHeaders.setContentType(responseContentType);
    responseHeaders.setContentLanguage(responseContentLanguage);
    responseHeaders.setContentDisposition(responseContentDispositon);
    responseHeaders.setCacheControl(responseCacheControl);
    responseHeaders.setExpires(cacheExpireStr);
    req.setResponseHeaders(responseHeaders);
    // 设置签名过期时间(可选),若未进行设置,则默认使用 ClientConfig 中的签名过期时间(1小时)
    // 这里设置签名在半个小时后过期
    Date expirationDate = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
    req.setExpiration(expirationDate);
    // 填写本次请求的参数
    req.addRequestParameter("param1", "value1");
    // 填写本次请求的头部
    // host 必填
    req.putCustomRequestHeader(Headers.HOST, cosClient.getClientConfig().getEndpointBuilder().buildGeneralApiEndpoint(bucketName));
    req.putCustomRequestHeader("header1", "value1");
    URL url = cosClient.generatePresignedUrl(req);
    System.out.println(url.toString());
    // 确认本进程不再使用 cosClient 实例之后,关闭之
    cosClient.shutdown();
    

    参数说明

    参数名称 描述 类型 是否必填
    req 预签名请求类 GeneratePresignedUrlRequest
    signHost 是否签入 Host 头部(推荐)默认 true boolean

    Request 成员说明:

    Request 成员 设置方法 描述 类型
    method 构造函数或 set 方法 HTTP 方法,可选:GET、POST、PUT、DELETE、HEAD HttpMethodName
    bucketName 构造函数或 set 方法 存储桶名称,存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范 String
    key 构造函数或 set 方法 对象键(Key)是对象在存储桶中的唯一标识,详情请参见 对象键 String
    expiration set 方法 签名过期的时间,可以设置任意一个未来的时间,不设置则默认是1小时之后过期 Date
    contentType set 方法 要签名的请求中的 Content-Type String
    contentMd5 set 方法 要签名的请求中的 Content-Md5 String
    responseHeaders set 方法 签名的下载请求中要覆盖的返回的 HTTP 头 ResponseHeaderOverrides
    versionId set 方法 在存储桶开启版本控制的时候,指定对象的版本号 String

    生成签名

    构造 COS 请求的签名。推荐使用临时密钥来生成签名。

    使用临时密钥(推荐)

    // 这里需要已经获取到临时密钥的结果。
    // 临时密钥的生成参考 https://www.tencentcloud.com/document/product/436/14048#cos-sts-sdk
    String tmpSecretId = "TMPSECRETID";
    String tmpSecretKey = "TMPSECRETKEY";
    String sessionToken = "SESSIONTOKEN";
    COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
    // 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://www.tencentcloud.com/document/product/436/13324)
    String key = "exampleobject";
    //若key不是以“/”开头,则需要在key的开头加上“/”,否则直接resource_path=key
    String resource_path="/" + key;
    ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
    // 用来生成签名
    COSSigner signer = new COSSigner();
    // 设置签名过期时间(可选),若未进行设置,则默认使用 ClientConfig 中的签名过期时间(1小时)
    // 这里设置签名在半个小时后过期
    Date expirationDate = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
    // 填写本次请求的参数
    Map<String, String> params = new HashMap<String, String>();
    params.put("param1", "value1");
    // 填写本次请求的头部
    Map<String, String> headers = new HashMap<String, String>();
    // host 必填
    headers.put(Headers.HOST, clientConfig.getEndpointBuilder().buildGeneralApiEndpoint(bucketName));
    headers.put("header1", "value1");
    // 请求的 HTTP 方法,上传请求用 PUT,下载请求用 GET,删除请求用 DELETE
    HttpMethodName method = HttpMethodName.GET;
    String sign = signer.buildAuthorizationStr(method, resource_path, headers, params, cred, expirationDate, true);
    

    使用永久密钥

    // 设置用户身份信息。
    // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.tencentcloud.com/cam/capi 进行查看和管理
    String secretId = "SECRETID";
    String secretKey = "SECRETKEY";
    COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
    // 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
    String bucketName = "examplebucket-1250000000";
    // 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://www.tencentcloud.com/document/product/436/13324)
    String key = "exampleobject";
    //若key不是以“/”开头,则需要在key的开头加上“/”,否则直接resource_path=key
    String resource_path="/" + key;
    ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
    // 用来生成签名
    COSSigner signer = new COSSigner();
    // 设置签名过期时间(可选),若未进行设置,则默认使用 ClientConfig 中的签名过期时间(1小时)
    // 这里设置签名在半个小时后过期
    Date expirationDate = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
    // 填写本次请求的参数
    Map<String, String> params = new HashMap<String, String>();
    params.put("param1", "value1");
    // 填写本次请求的头部
    Map<String, String> headers = new HashMap<String, String>();
    // host 必填
    headers.put(Headers.HOST, clientConfig.getEndpointBuilder().buildGeneralApiEndpoint(bucketName));
    headers.put("header1", "value1");
    // 请求的 HTTP 方法,上传请求用 PUT,下载请求用 GET,删除请求用 DELETE
    HttpMethodName method = HttpMethodName.GET;
    String sign = signer.buildAuthorizationStr(method, resource_path, headers, params, cred, expirationDate, true);
    

    生成限速的预签名下载 URL

    关于限速的使用说明,可参见 单链接限速

    请求示例

    以生成限速的预签名下载 URL 为例:

    public static void GenerateSimplePresignedDownloadUrl() {
          // 1 初始化用户身份信息(secretId, secretKey)
          COSCredentials cred = new BasicCOSCredentials("secretId", "secretKey");
          // 2 设置bucket的区域, COS地域的简称请参照 https://www.qcloud.com/document/product/436/6224
          ClientConfig clientConfig = new ClientConfig(new Region("COS_REGION"));
          // 如果要获取 https 的 url 则在此设置,否则默认获取的是 http url
          clientConfig.setHttpProtocol(HttpProtocol.https);
          // 3 生成cos客户端
          COSClient cosclient = new COSClient(cred, clientConfig);
          // bucket名需包含appid
          String bucketName = "examplebucket-1250000000";
          
          String key = "exampleobject";
          GeneratePresignedUrlRequest req =
                  new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);
          // 设置签名过期时间(可选), 若未进行设置则默认使用ClientConfig中的签名过期时间(1小时)
          // 这里设置签名在半个小时后过期
          Date expirationDate = new Date(System.currentTimeMillis() + 30 * 60 * 1000);
          req.setExpiration(expirationDate);
           // 填写本次请求的参数
          // 设定限速值,例如128KB/s
          req.addRequestParameter("x-cos-traffic-limit", "1048576");
           // 填写本次请求的头部。Host 必填
          req.putCustomRequestHeader(Headers.HOST,
          cosclient.getClientConfig().getEndpointBuilder().buildGeneralApiEndpoint(bucketName));
          //req.putCustomRequestHeader("header1", "value1");
           URL url = cosclient.generatePresignedUrl(req);
          System.out.println(url.toString());
           cosclient.shutdown();
      }
    
    联系我们

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

    技术支持

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

    7x24 电话支持