tencent cloud

Cloud Object Storage

임시 키 생성 및 사용 가이드

다운로드
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-07-15 11:24:25
AI 번역
키는 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 action 및 CI 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 이상 버전을 사용하십시오.

도움말 및 지원

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

피드백