tencent cloud

Cloud Object Storage

임시 키 생성 및 사용 가이드

Download
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-07-15 11:24:25
키는 COS에 요청을 보낼 때 사용하는 신원 인증 자격 증명으로, 임시 키와 영구 키를 포함합니다.임시 키는 프론트엔드 직접 업로드와 같은 임시 승인 시나리오에 적합하며, 영구 키는 신뢰할 수 있는 사용자와 보안성이 높은 시나리오에 적합합니다. 본 문서에서는 임시 키 사용 방법을 소개합니다.

임시 키 개요

임시 키(임시 액세스 자격 증명)은 CAM 클라우드 API에서 제공하는 인터페이스를 통해 권한이 제한된 키를 획득합니다. COS API 요청을 보낼 때는 임시 키 획득 인터페이스에서 반환된 정보의 TmpSecretId, TmpSecretKey 및 Token 세 가지 필드를 사용하여 서명을 계산합니다. 임시 키의 권한에 대한 자세한 내용은 임시 키로 COS 액세스를 참고하십시오.
주의:
임시 키로 액세스 권한을 부여할 때는 반드시 비즈니스 필요에 따라 최소 권한 원칙에 따라 권한을 부여하십시오.
모든 리소스(resource:*) 또는 모든 작업(action:*)에 대한 권한을 직접 부여할 경우, 권한 범위가 과도하게 넓어져 데이터 보안 위험이 발생할 수 있습니다.
임시 키를 신청할 때 action 권한 범위를 지정하면, 신청된 임시 키 역시 권한 범위 내에서만 작업을 수행할 수 있습니다. 예를 들어, 임시 키 신청 시 버킷 examplebucket-1-1250000000에 파일을 업로드할 수 있는 권한 범위를 지정했다면, 신청된 키는examplebucket-2-1250000000에 파일을 업로드할 수 없으며, 또한examplebucket-1-1250000000에서 파일을 다운로드할 수도 없습니다.
임시 키 생성 인터페이스의 기본 요청 빈도 제한은 초당 600회입니다.

임시 키 생성 방식

임시 키 신청 과정에서 권한 정책 policy 필드를 설정하여 작업과 리소스를 제한하고, 권한을 지정된 범위 내로 제한할 수 있습니다.
COS API 권한 부여 정책에 대해서는 다음을 참고하십시오:
임시 키는 다음과 같은 두 가지 방식으로 생성됩니다:
방식 1: COS STS SDK는 개발 언어 시나리오에 적합합니다.
방식 2: STS Cloud API는 사용자가 키를 보다 편리하고 신속하게 생성할 수 있도록 지원합니다.

방식 1: COS STS SDK

COS는 STS를 위해 SDK와 샘플을 제공하며, 현재 Java, Node.js, PHP, Python, Go 등 다양한 언어의 샘플을 보유하고 있습니다. 제공된 COS STS SDK 방식을 통해 임시 키를 획득할 수 있습니다. 각 SDK의 사용 설명은 GitHub의 README와 샘플을 참고하십시오. 각 언어별 GitHub 주소는 다음 표와 같습니다:
주의:
STS SDK는 STS 인터페이스 자체 버전 간 차이를 완화하기 위해, 반환 매개변수 구조가 STS 인터페이스와 완전히 일치하지 않을 수 있습니다. 상세 정보는 Java SDK 문서를 참조하십시오.

방식 2: STS Cloud API

STS Cloud API를 통해 임시 키를 획득하며, 요청 매개변수는 연합 신원 임시 액세스 자격 증명 획득을 참고하십시오. 예시 매개변수는 다음과 같습니다:
입력 매개변수
참고 값
설명
필수
Region
화베이 지방(베이징) ap-beijing
작업 대상 리소스가 속한 리전은 베이징입니다.
Name
test
사용자 정의 호출자의 영문 이름은 test입니다.
Policy
{"version":"2.0","statement":[{"effect":"allow","action":["name/cos:PutObject","name/cos:DeleteObject"],"resource":"*"}]}
정책 문법 버전 version을 '2.0'으로 기술합니다.
선언에 의해 생성된 결과 effect는 '허용'입니다.
허용된 작업 action을 'name/cos:PutObject'(객체 업로드), 'name/cos:DeleteObject'(객체 삭제)로 기술하며, 더 많은 인터페이스는 CAM을 지원하는 COS 비즈니스 인터페이스를 참고하십시오.
승인된 구체적인 데이터 resource를 기술하고, 작업 action에 대한 모든 리소스의 작업 권한을 부여합니다.
DurationSeconds
3600
임시 키의 유효 기간을 3600초로 지정합니다. 지정하지 않을 경우 기본값은 1800초입니다.
아니요
입력 매개변수에서 참조 값을 선택하거나 입력한 후 요청 시작을 클릭하면 TmpSecretId, TmpSecretKey, Token을 획득할 수 있습니다.


임시 키 생성 코드 예시

Java SDK를 사용하는 경우, 먼저 Java SDK를 다운로드한 후 다음 코드를 실행하여 임시 키 예시를 획득하십시오:
github에서 제공하는 maven 통합 방법에 따라 java sts sdk를 가져오고, 3.1.1 이상 버전을 사용합니다.

import java.util.TreeMap;
import com.tencent.cloud.CosStsClient;
import com.tencent.cloud.Policy;
import com.tencent.cloud.Response;
import com.tencent.cloud.Statement;
import com.tencent.cloud.cos.util.Jackson;

public class demo {
public static void main(String[] args) {
TreeMap<String, Object> config = new TreeMap<String, Object>();
try {
//여기의 SecretId와 SecretKey는 임시 키 신청에 사용되는 영구 신원(마스터 계정, 서브 계정 등)을 나타내며, 서브 계정은 버킷 작업 권한을 보유해야 합니다.
String secretId = System.getenv("secretId");//사용자의 SecretId입니다. 서브 계정 키 사용을 권장하며, 권한 부여 시 최소 권한 지침을 준수하여 사용 위험을 줄이십시오. 서브 계정 키 획득 방법은 https://www.tencentcloud.com/document/product/598/32675을 참고하십시오.
String secretKey = System.getenv("secretKey");//사용자의 SecretKey입니다. 서브 계정 키 사용을 권장하며, 권한 부여 시 최소 권한 지침을 준수하여 사용 위험을 줄이십시오. 서브 계정 키 획득 방법은 https://www.tencentcloud.com/document/product/598/32675을 참고하십시오.
//Tencent Cloud api 키 SecretId로 교체하십시오.
config.put("secretId", secretId);
//Tencent Cloud api 키 SecretKey로 교체하십시오.
config.put("secretKey", secretKey);

//policy 초기화
Policy policy = new Policy();

//도메인 설정:
//Tencent Cloud cvm을 사용하는 경우, 내부 도메인을 설정할 수 있습니다.
//config.put("host", "sts.internal.tencentcloudapi.com");

//임시 키 유효 기간은 단위가 초이며, 기본값은 1800초입니다. 현재 마스터 계정은 최대 2시간(7200초), 서브 계정은 최대 36시간(129600초)까지 설정 가능합니다.
config.put("durationSeconds", 1800);
//사용자의 버킷으로 교체하십시오.
config.put("bucket", "examplebucket-1250000000");
//버킷이 위치한 리전으로 교체하십시오.
config.put("region", "ap-chongqing");

//statement 하나를 생성합니다.
Statement statement = new Statement();
//선언 설정 결과는 작업을 허용합니다.
statement.setEffect("allow");
/**
* 키 권한 목록. 여기에서 이번 임시 키에 필요한 권한을 지정해야 합니다.
* 권한 목록은 https://www.tencentcloud.com/document/product/436/30580을 참고하십시오.
* 규칙은 {project}:{interfaceName}입니다.
* project : 제품 약어. cos 관련 권한 부여의 값은 cos이며, CI(데이터 처리) 관련 권한 부여의 값은 ci입니다.
* 모든 인터페이스에 대한 권한 부여는 *로 표시합니다. 예: cos:*, ci:*.
* 작업 권한 일괄 추가:
*/
statement.addActions(new String[]{
"cos:PutObject",
//폼 업로드, 미니프로그램 업로드
"cos:PostObject",
//멀티파트 업로드
"cos:InitiateMultipartUpload",
"cos:ListMultipartUploads",
"cos:ListParts",
"cos:UploadPart",
"cos:CompleteMultipartUpload",
//처리 관련 인터페이스는 일반적으로 CI 제품에 속하며, 권한은 ci로 시작합니다.
//미디어 처리 작업 생성
"ci:CreateMediaJobs",
//파일 압축
"ci:CreateFileProcessJobs"
});

/**
* 허용된 경로 접두사로 변경합니다. 본인 사이트의 사용자 로그인 상태에 따라 허용된 업로드 경로를 판단할 수 있습니다.
* 리소스 표현식 규칙은 cos와 ci 두 가지로 구분됩니다.
* 데이터 처리 및 심사 관련 인터페이스는 ci 리소스 권한을 부여해야 합니다.
* cos : qcs::cos:{region}:uid/{appid}:{bucket}/{path}
* ci : qcs::ci:{region}:uid/{appid}:bucket/{bucket}/{path}
* {path}의 대표적인 권한 부여 시나리오 몇 가지를 나열합니다:
* 1. 모든 객체에 대한 액세스 허용: '*'
* 2. 지정된 객체에 대한 액세스 허용: 'a/a1.txt', 'b/b1.txt'
* 3. 지정된 접두사를 가진 객체에 대한 액세스 허용: 'a*', 'a/*', 'b/*'
* '*'를 입력하면 사용자가 모든 리소스에 액세스할 수 있습니다. 비즈니스 요구가 아닌 경우 최소 권한 원칙에 따라 사용자에게 적절한 액세스 권한 범위를 부여하십시오.
*
* 예시: examplebucket-1250000000 버킷 디렉터리 아래의 모든 리소스를 cos와 ci에 권한 부여하며, 두 개의 Resource에 대한 권한을 부여합니다.
*/
statement.addResources(new String[]{
"qcs::cos:ap-chongqing:uid/1250000000:examplebucket-1250000000/*",
"qcs::ci:ap-chongqing:uid/1250000000:bucket/examplebucket-1250000000/*"});

//policy에 statement 하나를 추가합니다.
//여러 개를 추가할 수 있습니다.
policy.addStatement(statement);
//Policy 예시를 String으로 변환할 때는 모든 json 변환 방식을 사용할 수 있으며, 여기서는 본 SDK에 내장된 권장 방식을 사용합니다.
config.put("policy", Jackson.toJsonPrettyString(policy));

Response response = CosStsClient.getCredential(config);
System.out.println(response.credentials.tmpSecretId);
System.out.println(response.credentials.tmpSecretKey);
System.out.println(response.credentials.sessionToken);
} catch (Exception e) {
e.printStackTrace();
throw new IllegalArgumentException("no valid secret !");
}
}
}
구성 매개변수에 대한 설명은 다음과 같습니다:
필드
참고 값
설명
필수
secretId
실제로 획득한 SecretId를 기준으로 합니다.
서브 계정 키 획득 방법은 서브 계정 액세스 키 관리를 참고하십시오.
secretKey
실제로 획득한 SecretKey를 기준으로 합니다.
서브 계정 키 획득 방법은 서브 계정 액세스 키 관리를 참고하십시오.
durationSeconds
1800
임시 키의 유효 기간을 1800초로 지정합니다.
아니요
bucket
examplebucket-1250000000
실제 버킷 이름을 기준으로 합니다.
region
ap-guangzhou
실제 버킷이 위치한 리전을 기준으로 합니다.
allowPrefixes
"*"
모든 객체에 대한 액세스를 허용합니다. 단, 비즈니스상 필요하지 않은 경우 최소 권한 원칙에 따라 사용자에게 적절한 권한 범위를 부여하십시오.
allowActions
"cos:PutObject",
"cos:PostObject",
"cos:InitiateMultipartUpload",
"cos:ListMultipartUploads",
"cos:ListParts",
"cos:UploadPart",
"cos:CompleteMultipartUpload",
// 처리 관련 인터페이스는 일반적으로 CI 제품에 해당하며, 권한은 'ci'로 시작합니다.
"ci:CreateMediaJobs",
"ci:CreateFileProcessJobs"
PutObject: 객체 업로드
PostObject: 폼을 통한 객체 업로드
InitiateMultipartUpload: 멀티파트 업로드 작업 초기화
ListMultipartUploads: 멀티파트 업로드 작업 조회
ListParts: 업로드된 파트 조회
UploadPart: 객체 파트 업로드
CompleteMultipartUpload: 멀티파트 업로드 작업 완료
CreateMediaJobs: 미디어 처리 작업 생성
CreateFileProcessJobs: 파일 압축
추가 인터페이스는 cos actionCI action을 참고하십시오.

사용 사례: 임시 키로 COS 액세스

COS API에서 임시 키를 사용하여 COS 서비스에 액세스할 때는 x-cos-security-token 필드를 통해 임시 sessionToken을 전달하고, 임시 SecretId와 SecretKey를 통해 서명을 계산합니다.
COS Java SDK를 예로 들어, 임시 키를 사용하여 COS에 액세스하는 예시는 다음과 같습니다:
설명:
다음 예시를 실행하기 전에 GitHub 프로젝트에서 cos-java-sdk-v5 설치 패키지를 가져오십시오.
github에서 제공하는 maven 통합 방식을 따라 cos xml java sdk를 가져옵니다.

import com.qcloud.cos.COSClient; import com.qcloud.cos.ClientConfig; import com.qcloud.cos.auth.BasicSessionCredentials; import com.qcloud.cos.auth.COSCredentials; import com.qcloud.cos.exception.CosClientException; import com.qcloud.cos.exception.CosServiceException; import com.qcloud.cos.model.ObjectMetadata; import com.qcloud.cos.model.PutObjectRequest; import com.qcloud.cos.model.PutObjectResult; import com.qcloud.cos.region.Region; import java.io.File;
public class Demo {
public static void main(String[] args) throws Exception {

// 사용자 기본 정보
String tmpSecretId = "COS_SECRETID"; // STS 인터페이스에서 반환된 임시 SecretId로 교체합니다.
String tmpSecretKey = "COS_SECRETKEY"; // STS 인터페이스에서 반환된 임시 SecretKey로 교체합니다.
String sessionToken = "Token"; // STS 인터페이스에서 반환된 임시 Token으로 교체합니다.

// 1 사용자 신원 정보 초기화(secretId, secretKey)
COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
// 2 버킷 리전 설정, 상세 정보는 COS 리전 <https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1>을 참고하십시오.
ClientConfig clientConfig = new ClientConfig(new Region("ap-guangzhou"));
// 3 cos 클라이언트 생성
COSClient cosclient = new COSClient(cred, clientConfig);
//버킷 이름에 appid를 포함해야 합니다.
String bucketName = "examplebucket-1250000000";

String key = "exampleobject";
// 객체 업로드, 20M 이하 파일에 해당 인터페이스 사용을 권장합니다.
File localFile = new File("src/test/resources/text.txt");
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

// x-cos-security-token 헤더 필드 설정
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setSecurityToken(sessionToken);
putObjectRequest.setMetadata(objectMetadata);

try {
PutObjectResult putObjectResult = cosclient.putObject(putObjectRequest);
// 성공: putobjectResult가 파일의 etag를 반환합니다.
String etag = putObjectResult.getETag();
} catch (CosServiceException e) {
//실패, CosServiceException이 발생합니다.
e.printStackTrace();
} catch (CosClientException e) {
//실패, CosClientException이 발생합니다.
e.printStackTrace();
}

// 클라이언트 종료
cosclient.shutdown();

}
}
구성 매개변수에 대한 설명은 다음과 같습니다:
필드
참고 값
설명
COS_SECRETID
실제로 획득한 SecretId를 기준으로 합니다.
STS 인터페이스에서 반환된 임시 SecretId로 교체합니다.
COS_SECRETKEY
실제로 획득한 SecretKey를 기준으로 합니다.
STS 인터페이스에서 반환된 임시 SecretKey로 교체합니다.
Token
실제로 획득한 Token을 기준으로 합니다.
STS 인터페이스에서 반환된 임시 Token으로 교체합니다.
new Region
ap-guangzhou
실제 버킷이 위치한 리전을 기준으로 합니다.
bucketName
examplebucket-1250000000
실제 버킷 이름을 기준으로 합니다.
key
exampleobject
예: /test/demo.txt. 업로드된 객체의 위치는 /test이며, 이름은 demo.txt입니다.
new File
src/test/resources/text.txt
업로드할 객체의 로컬 위치는 src/test/resources/이며, 파일 이름은 test, 형식은 txt입니다.

자주 묻는 질문

JSONObject 패키지 충돌로 인한 NoSuchMethodError?

답: 3.1.0 이상 버전을 사용하십시오.

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백