对象存储生成预签名 URL-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 Java  SDK 实现生成对象预签名链接的示例代码和描述。
注意事项
生成预签名 URL 支持使用永久密钥或临时密钥。
获取签名/预签名函数，默认签入 Header Host；您也可以选择不签入 Header Host，但可能导致请求失败或安全漏洞。
2024年1月1日后创建的桶 不支持使用默认域名在浏览器预览文件，建议您配置自定义域名，详情请参见 存储桶切换自定义域名。
相关示例
功能名称
描述
示例代码
生成预签名 URL
对象存储（Cloud Object Storage，COS）支持使用预签名 URL 进行对象的上传、下载，原理是将签名嵌入 URL 生成签名链接。
﻿GitHub完整示例﻿
前期准备
创建 COSClient
调用 COS 的接口之前，必须先创建一个 COSClient 的实例。
说明：
COSClient 实例是并发安全的，这里推荐一个进程只创建一个 COSClient 实例，当不会再通过这个实例发起请求的时候，再选择关闭这个实例。
// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
    // 设置用户身份信息。
    // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
    String secretId = System.getenv("secretId");//用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
    String secretKey = System.getenv("secretKey");//用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
    COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
    
    // ClientConfig 中包含了后续请求 COS 的客户端设置：
    ClientConfig clientConfig = new ClientConfig();
    
    // 设置 bucket 的地域
    // COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
    clientConfig.setRegion(new Region("COS_REGION"));
         
    // 以下的设置，是可选的：
    
    // 设置 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 实例。
说明：
COSClient 实例是并发安全的，这里推荐一个进程只创建一个 COSClient 实例，当不会再通过这个实例发起请求的时候，再选择关闭这个实例。
使用临时密钥创建 COSClient 实例之前，需要先生成临时密钥，本 SDK 并不能生成临时密钥，而需要使用额外的操作来生成，参考 临时密钥生成及使用指引。
// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
    // 这里需要已经获取到临时密钥的结果。
    // 临时密钥的生成参见 https://cloud.tencent.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://cloud.tencent.com/document/product/436/6224
    clientConfig.setRegion(new Region("COS_REGION"));
﻿
    // 以下的设置，是可选的：
﻿
    // 设置 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
当不会再通过一个COSClient实例发起请求的时候，请及时将其关闭，防止资源泄露。
cosclient.shutdown();
使用案例
生成预签名 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://cloud.tencent.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）是对象在存储桶中的唯一标识，详情请参见 对象键（注意：用户无需对 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://cloud.tencent.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）是对象在存储桶中的唯一标识，详情请参见 对象键（注意：用户无需对 Key 进行编码操作）
String
expiration
set 方法
签名过期的时间，可以设置任意一个未来的时间，不设置则默认是1小时之后过期
Date
contentType
set 方法
要签名的请求中的 Content-Type
String
contentMd5
set 方法
要签名的请求中的 Content-Md5
String
responseHeaders
set 方法
签名的下载请求中要覆盖的返回的 HTTP 头
ResponseHeaderOverrides
versionId
set 方法
在存储桶开启版本控制的时候，指定对象的版本号
String
生成预签名上传 URL并使用该 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";
String key = "aaa.txt";
Date expirationTime = new Date(System.currentTimeMillis() + 30 * 60 * 1000L);
// 填写本次请求的 header。Host 头部会自动补全，只需填入其他头部
Map<String, String> headers = new HashMap<String,String>();
// 填写本次请求的 params。
Map<String, String> params = new HashMap<String,String>();

URL url = cosClient.generatePresignedUrl(bucketName, key, expirationTime, HttpMethodName.PUT, headers, params);
System.out.println(url.toString());
int retryIndex = 0;
while (true) {
    try {
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setDoOutput(true);
        connection.setRequestMethod("PUT");
        OutputStreamWriter out = new OutputStreamWriter(connection.getOutputStream());
        // 写入要上传的数据
        out.write("This text uploaded as object.");
        out.close();
        int responseCode = connection.getResponseCode();
        System.out.println("Service returned response code " + responseCode);
        // 5xx 重试3次
        if (responseCode / 100 != 5 || retryIndex >= 3) {
            break;
        }
        System.out.println("will retry, retryIndex: " + retryIndex);
        retryIndex++;
    } catch (ProtocolException e) {
        e.printStackTrace();
        break;
    } catch (IOException e) {
        e.printStackTrace();
        break;
    }
}
        
// 确认本进程不再使用 cosClient 实例之后，关闭即可
cosClient.shutdown();
参数说明
参数名称
描述
类型
是否必填
method
HTTP 方法，可选：GET、POST、PUT、DELETE、HEAD
HttpMethodName
是
bucketName
存储桶名称，存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范﻿
String
是
key
对象键（Key）是对象在存储桶中的唯一标识，详情请参见 对象键（注意：用户无需对 Key 进行编码操作）
String
是
expiration
签名过期的时间，可以设置任意一个未来的时间，不设置则默认是1小时之后过期
Date
否
headers
签名头部
Map<String, String>
否
params
签名参数
Map<String, String>
否
signPrefixMode
是否以 sign 参数指定签名（不推荐），默认 false
boolean
否
signHost
是否签入 Host 头部（推荐），默认 true
boolean
否
﻿
﻿

功能名称	描述	示例代码
生成预签名 URL	对象存储（Cloud Object Storage，COS）支持使用预签名 URL 进行对象的上传、下载，原理是将签名嵌入 URL 生成签名链接。	GitHub完整示例

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

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

生成预签名 URL

本页目录：

简介

注意事项

相关示例

前期准备

创建 COSClient

使用临时密钥创建 COSClient

关闭 COSClient

使用案例

生成预签名 URL

方法原型

请求示例

参数说明

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

方法原型

请求示例

参数说明

生成预签名上传 URL并使用该 URL 上传对象

方法原型

请求示例

参数说明