tencent cloud

Cloud Object Storage

동향 및 공지
릴리스 노트
제품 공지
제품 소개
제품 개요
기능 개요
적용 시나리오
제품 장점
기본 개념
리전 및 액세스 도메인
규격 및 제한
제품 요금
과금 개요
과금 방식
과금 항목
프리 티어
과금 예시
청구서 보기 및 다운로드
연체 안내
FAQ
빠른 시작
콘솔 시작하기
COSBrowser 시작하기
사용자 가이드
요청 생성
버킷
객체
데이터 관리
일괄 프로세스
글로벌 가속
모니터링 및 알람
운영 센터
데이터 처리
스마트 툴 박스 사용 가이드
데이터 워크플로
애플리케이션 통합
툴 가이드
툴 개요
환경 설치 및 설정
COSBrowser 툴
COSCLI 툴
COSCMD 툴
COS Migration 툴
FTP Server 툴
Hadoop 툴
COSDistCp 툴
HDFS TO COS 툴
온라인 도구 (Onrain Dogu)
자가 진단 도구
실습 튜토리얼
개요
액세스 제어 및 권한 관리
성능 최적화
AWS S3 SDK를 사용하여 COS에 액세스하기
데이터 재해 복구 백업
도메인 관리 사례
이미지 처리 사례
COS 오디오/비디오 플레이어 사례
데이터 다이렉트 업로드
데이터 보안
데이터 검증
빅 데이터 사례
COS 비용 최적화 솔루션
3rd party 애플리케이션에서 COS 사용
마이그레이션 가이드
로컬 데이터 COS로 마이그레이션
타사 클라우드 스토리지 데이터를 COS로 마이그레이션
URL이 소스 주소인 데이터를 COS로 마이그레이션
COS 간 데이터 마이그레이션
Hadoop 파일 시스템과 COS 간 데이터 마이그레이션
데이터 레이크 스토리지
클라우드 네이티브 데이터 레이크
메타데이터 가속
데이터 레이크 가속기 GooseFS
데이터 처리
데이터 처리 개요
이미지 처리
미디어 처리
콘텐츠 조정
파일 처리
문서 미리보기
장애 처리
RequestId 가져오기
공용 네트워크로 COS에 파일 업로드 시 속도가 느린 문제
COS 액세스 시 403 에러 코드 반환
리소스 액세스 오류
POST Object 자주 발생하는 오류
보안 및 컴플라이언스
데이터 재해 복구
데이터 보안
액세스 관리
자주 묻는 질문
인기 질문
일반 문제
과금
도메인 규정 준수 문제
버킷 설정 문제
도메인 및 CDN 문제
파일 작업 문제
로그 모니터링 문제
권한 관리
데이터 처리 문제
데이터 보안 문제
사전 서명 URL 관련 문제
SDK FAQ
툴 관련 문제
API 관련 문제
Agreements
Service Level Agreement
개인 정보 보호 정책
데이터 처리 및 보안 계약
연락처
용어집
문서Cloud Object Storage

매뉴얼

포커스 모드
폰트 크기
마지막 업데이트 시간: 2025-08-05 16:51:28

다운로드 및 설치

관련 리소스

COS의 XML 미니프로그램 SDK 소스 코드 다운로드 주소: XML 미니프로그램 SDK
SDK 고속 다운로드 주소: XML 미니프로그램 SDK
예시 Demo 다운로드 주소: XML 미니프로그램 SDK Demo
SDK 문서의 모든 예시 코드는 SDK 코드 예시를 참고하십시오.
SDK 로그 업데이트는 ChangeLog를 참고하십시오.
SDK FAQ는 미니프로그램 SDK FAQ를 참고하십시오.
설명:
SDK 사용 시 함수 또는 메소드 없음 등 오류가 발생하였을 경우, 먼저 SDK를 최신 버전으로 업데이트한 후 재시도하십시오.

환경 종속

1. 해당 SDK는 WeChat 미니프로그램 환경에만 적용됩니다.
2. COS 콘솔에 로그인해 버킷을 생성한 후 버킷 이름과 리전 정보를 획득합니다.
3. CAM 콘솔에 로그인해 프로젝트의 SecretId와 SecretKey를 획득합니다.
설명:
본 문서에 나오는 SecretId, SecretKey, Bucket 등의 명칭에 대한 의미와 획득 방법은 COS 용어 정보를 참고하십시오.

SDK 설치

미니프로그램 SDK 설치 방법은 수동 설치와 npm 설치 두 가지입니다. 구체적인 설치 방법은 다음과 같습니다.

수동 설치

소스 코드 파일의 cos-wx-sdk-v5.js를 사용자의 미니프로그램 코드와 루트 디렉터리의 임의 경로로 복사하고, 상대 경로를 참고합니다.
var COS = require('./lib/cos-wx-sdk-v5.js')

npm 설치

미니프로그램 코드가 webpack 패키지를 사용한 경우, npm을 통해 종속 설치합니다.
npm install cos-wx-sdk-v5
그 중 미니프로그램 코드는 var COS = require('cos-wx-sdk-v5');를 사용하여 참고합니다.

사용하기

미니프로그램 도메인 화이트리스트 설정

미니프로그램에서 COS를 요청하면 WeChat 공식 계정에 로그인해 [개발] > [개발 설정] > [서버 도메인]을 선택하고 도메인 화이트리스트를 설정해야 합니다. SDK는 두 개의 인터페이스를 사용합니다.
1. cos.postObject는 wx.uploadFile 방법을 사용합니다.
2. 기타 방법은 wx.request 방법을 사용합니다.
해당 화이트리스트에서 COS 도메인을 설정해야 합니다. 화이트리스트 형식은 두 가지가 있습니다.
1. 표준 요청인 경우 버킷 도메인을 화이트리스트로 설정할 수 있습니다. 예: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
2. 미니프로그램에서 사용하는 버킷이 많은 경우 확장명을 선택하여 COS를 요청할 수 있습니다. SDK 인스턴스화 시 ForcePathStyle: true를 전송해야 합니다. 해당 방식은 리전 도메인을 화이트리스트로 설정해야 합니다. 예: cos.ap-guangzhou.myqcloud.com

초기화

var COS = require('./lib/cos-wx-sdk-v5.js')
var cos = new COS({
// ForcePathStyle: true, // 많은 버킷을 사용한 경우 확장명을 열어 설정한 화이트리스트 수를 줄이면 요청 시 리전 도메인을 사용합니다.
getAuthorization: function (options, callback) {
// 임시 키 비동기 획득
wx.request({
url: 'https://example.com/server/sts.php',
data: {
bucket: options.Bucket,
region: options.Region,
},
dataType: 'json',
success: function (result) {
var data = result.data;
var credentials = data && data.credentials;
if (!data || !credentials) return console.error('credentials invalid');
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
XCosSecurityToken: credentials.sessionToken,
// 사용자 브라우저 로컬 시간과의 편차가 너무 커 서명에 오류가 발생하지 않도록 서버 시간을 서명 시작 시간으로 반환할 것을 권장합니다.
StartTime: data.startTime, // 타임스탬프. 단위: 초. 예: 1580000000
ExpiredTime: data.expiredTime, // 타임스탬프. 단위: 초. 예: 1580000900
});
}
});
}
});

// 이어서 cos 인스턴스를 통해 COS 요청을 호출할 수 있습니다.
// TODO

설정 항목

사용 예시

COS SDK 인스턴스 한 개를 생성합니다. COS SDK는 다음과 같은 형식 생성을 지원합니다.
형식1(권장): 백그라운드에서 임시 키를 획득하여 프런트 엔드로 보내고, 프런트 엔드에서 서명을 계산합니다.
var cos = new COS({
// 필수 매개변수
getAuthorization: function (options, callback) {
// 서버 JS와 PHP 예시: https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/
// 서버의 기타 언어는 COS STS SDK: https://github.com/tencentyun/qcloud-cos-sts-sdk를 참고하십시오.
// STS 상세 문서 가이드는 https://www.tencentcloud.com/document/product/436/14048을 참고하십시오.
wx.request({
url: 'https://example.com/server/sts.php',
data: {
// options에서 필요한 매개변수 획득 가능
},
success: function (result) {
var data = result.data;
var credentials = data && data.credentials;
if (!data || !credentials) return console.error('credentials invalid');
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
XCosSecurityToken: credentials.sessionToken,
// 사용자 브라우저 로컬 시간과의 편차가 너무 커 서명에 오류가 발생하지 않도록 서버 시간을 서명 시작 시간으로 반환할 것을 권장합니다.
StartTime: data.startTime, // 타임스탬프. 단위: 초. 예: 1580000000
ExpiredTime: data.expiredTime, // 타임스탬프. 단위: 초. 예: 1580000900
});
}
});
}
});
설명:
임시 키 생성 및 사용에 대한 자세한 내용은 임시 키 생성 및 사용 가이드를 참고하십시오.
형식2(권장): 세밀한 권한 제어. 백그라운드에서 임시 키를 획득하여 프런트 엔드로 보냅니다. 동일한 요청을 하는 경우에만 프런트 엔드가 임시 키를 재사용합니다. 백그라운드는 Scope을 통해 권한을 세밀하게 제어합니다.
var cos = new COS({
// 필수 매개변수
getAuthorization: function (options, callback) {
// 서버 예시: https://github.com/tencentyun/qcloud-cos-sts-sdk/edit/master/scope.md
wx.request({
url: 'https://example.com/server/sts-scope.php',
data: JSON.stringify(options.Scope),
success: function (result) {
var data = result.data;
var credentials = data && data.credentials;
if (!data || !credentials) return console.error('credentials invalid');
callback({
TmpSecretId: credentials.tmpSecretId,
TmpSecretKey: credentials.tmpSecretKey,
XCosSecurityToken: credentials.sessionToken,
// 사용자 브라우저 로컬 시간과의 편차가 너무 커 서명에 오류가 발생하지 않도록 서버 시간을 서명 시작 시간으로 반환할 것을 권장합니다.
StartTime: data.startTime, // 타임스탬프. 단위: 초. 예: 1580000000
ExpiredTime: data.expiredTime, // 타임스탬프. 단위: 초. 예: 1580000900
ScopeLimit: true, // 세밀한 권한 제어는 true로 설정해 키가 동일한 요청을 하는 경우에만 재사용하도록 제한합니다.
});
}
});
}
});
설명:
임시 키 생성 및 사용에 대한 자세한 내용은 임시 키 생성 및 사용 가이드를 참고하십시오.
형식3(권장하지 않음): 매번 프런트 엔드가 요청하기 전에 getAuthorization을 통해 서명을 획득하고, 백그라운드는 고정 키 또는 임시 키를 사용해 서명을 계산하여 프런트 엔드로 반환해야 합니다. 해당 형식의 멀티파트 업로드 권한은 제어하기 쉽지 않기 때문에 사용을 권장하지 않습니다.
var cos = new COS({
// 필수 매개변수
getAuthorization: function (options, callback) {
// 서버에서 서명을 획득합니다. 해당 언어의 COS SDK: https://www.tencentcloud.com/document/product/436/6474?from_cn_redirect=1를 참고하십시오.
// 주의사항: 보안 리스크가 있기 때문에 백그라운드는 method, pathname을 통해 권한을 엄격히 제어해야 합니다. 예: put / 비허용 등
wx.request({
url: 'https://example.com/server/auth.php',
data: JSON.stringify(options.Scope),
success: function (result) {
var data = result.data;
if (!data || !data.authorization) return console.error('authorization invalid');
callback({
Authorization: data.authorization,
// XCosSecurityToken: data.sessionToken, // 임시 키를 사용하는 경우, sessionToken을 XCosSecurityToken에 전송해야 합니다.
});
}
});
},
});
형식4(권장하지 않음): 프런트 엔드는 고정 키를 사용해 서명을 계산합니다. 해당 형식은 프런트 엔드 디버깅에 적합하며, 사용 시 키가 노출되지 않도록 주의하십시오.
// SECRETID와 SECRETKEY는 https://console.tencentcloud.com/cam/capi에 로그인하여 조회 및 관리하십시오.
var cos = new COS({
SecretId: 'SECRETID',
SecretKey: 'SECRETKEY',
});

구조 함수 매개변수 설명

매개변수 이름
매개변수 설명
유형
필수 입력
SecretId
사용자의 SecretId
String
아니요
SecretKey
사용자의 SecretKey. 키가 노출되지 않도록 프런트 엔드 디버깅 시에만 사용하는 것을 권장합니다.
String
아니요
FileParallelLimit
동일한 인스턴스에 업로드하는 파일의 동시 전송 수. 기본값: 3
Number
아니요
ChunkParallelLimit
동일한 업로드 파일의 멀티파트 동시 전송 수. 기본값: 3
Number
아니요
ChunkRetryTimes
멀티파트 업로드 및 멀티파트 복사 시 오류가 발생하여 재시도한 횟수. 기본값: 3(첫 번째 시도를 더하면 요청은 총 4번)
Number
아니요
ChunkSize
멀티파트 업로드 시 각 파트의 바이트 수. 기본값: 1048576(1MB)
Number
아니요
SliceSize
uploadFiles로 일괄 업로드 시, 파일 크기가 해당 값보다 크면 멀티파트 업로드 sliceUploadFile을 사용하고, 그렇지 않을 경우 간편 업로드 putObject를 사용합니다. 기본값: 1048576(1MB)
Number
아니요
CopyChunkParallelLimit
멀티파트 복사 작업 중에 멀티파트 업로드한 동시 전송 수. 기본값: 20
Number
아니요
CopyChunkSize
sliceCopyFile로 파일 멀티파트 복사 시, 각 파트의 바이트 수. 기본값: 10485760(10MB)
Number
아니요
CopySliceSize
sliceCopyFile로 파일 멀티파트 복사 시, 파일 크기가 해당 값보다 크면 멀티파트 복사 sliceCopyFile을 사용하고, 그렇지 않을 경우 간편 복사 putObjectCopy를 사용합니다. 기본값: 10485760(10MB)
Number
아니요
ProgressInterval
업로드 진행률 콜백 방법 onProgress의 콜백 빈도. 단위: ms, 기본값: 1000
Number
아니요
Protocol
요청 시 사용하는 프로토콜. 옵션 항목으로 https:http:가 있습니다. 기본적으로 현재 페이지가 http:인 경우 http:를 사용하고, 아닌 경우 https:를 사용합니다.
String
아니요
ServiceDomain
getService 방법 호출 시 요청하는 도메인. 예: service.cos.myqcloud.com
String
아니요
Domain
버킷 및 객체 작업 API 호출 시 요청 도메인을 사용자 정의합니다. "{Bucket}.cos.{Region}.myqcloud.com" 과 같은 템플릿을 사용할 수 있으며, API 호출 시 매개변수로 전달하는 Bucket 및 Region으로 변경할 수 있습니다.
String
아니요
UploadQueueSize
업로드 큐 최대 길이. 초과된 작업이 waiting, checking, uploading 상태가 아닌 경우 정리합니다. 기본값: 10000
Number
아니요
ForcePathStyle
강제 사용 후 확장명 모드로 요청 발송. 확장명 모드의 Bucket에 도메인 뒤의 pathname을 넣고, 서명 pathname 계산을 추가합니다. 기본값: false
Boolean
아니요
UploadCheckContentMd5
파일을 강제 업로드하여 Content-MD5 검증. 파일에 대해 Body를 요청하여 md5를 계산하고 header의 Content-MD5 필드에 올립니다. 기본값: false
Boolean
아니요
getAuthorization
서명을 획득하는 콜백 방법. SecretId, SecretKey가 없는 경우 이 매개변수는 필수입니다.
주의사항: 해당 콜백 방법은 인스턴스 초기화 시 전송되며, 인스턴스로 인터페이스를 호출해야 실행되어 서명을 획득합니다.
Function
아니요

getAuthorization 콜백 함수 설명의 함수 설명(형식1 사용)

getAuthorization: function(options, callback) { ... }
getAuthorization의 콜백 매개변수 설명:
매개변수 이름
매개변수 설명
유형
options
임시 키에 필요한 매개변수 객체 획득
Object
- Bucket
버킷의 이름. 이름 생성 규칙은 BucketName-APPID이며, 여기에 입력하는 버킷 이름은 반드시 해당 형식을 따라야 합니다.
String
- Region
버킷이 위치한 리전. 열거 값은 리전 및 액세스 도메인을 참고하십시오.
String
callback
임시 키 획득 후 리턴 방법
Function
임시 키 획득 후 callback은 하나의 객체를 리턴합니다. 리턴 객체의 속성 리스트는 다음과 같습니다.
속성 이름
매개변수 설명
유형
필수 입력
TmpSecretId
획득한 임시 키의 tmpSecretId
String
TmpSecretKey
다시 획득한 임시 키의 tmpSecretKey
String
아니요
XCosSecurityToken
획득한 임시 키의 sessionToken. 해당 header의 x-cos-security-token 필드
String
아니요
StartTime
키를 획득한 시작 시간. 즉 획득한 시간의 타임스탬프. 단위: 초. startTime. 예: 1580000000. 서명 시작 시간에 사용됩니다. 해당 매개변수를 전송하면 프런트 엔드 시간의 편차로 인한 서명 만료 문제를 방지할 수 있습니다.
String
아니요
ExpiredTime
획득한 임시 키의 expiredTime, 타임아웃 시간의 타임스탬프. 단위 초. 예: 1580000900
String
아니요

getAuthorization 콜백 함수 설명(형식2 사용)

getAuthorization: function(options, callback) { ... }
getAuthorization 함수 설명 및 콜백 매개변수 설명:
매개변수 이름
매개변수 설명
유형
options
서명에 필요한 매개변수 객체 획득
Object
- Method
현재 요청한 Method
Object
- Pathname
요청 경로. 서명 계산에 사용
String
- Key
객체 키(Object의 이름). 객체는 버킷에 있는 고유 식별자입니다. 자세한 내용은 객체 개요를 참고하십시오. 주의사항: 인스턴스로 요청한 인터페이스가 객체 작업과 관련된 인터페이스가 아닐 경우, 해당 매개변수는 빈칸으로 표시됩니다.
String
- Query
현재 요청한 query 매개변수 객체. {key: 'val'} 의 형식
Object
- Headers
현재 요청한 header 매개변수 객체. {key: 'val'}의 형식
Object
callback
임시 키 획득 후 콜백
Function
getAuthorization 계산 완료 후 callback 리턴 매개변수는 두 가지 형식을 지원합니다. 형식1: 자격 증명 문자열 Authorization 리턴 형식2: 하나의 객체 리턴. 리턴 속성 리스트는 다음과 같습니다.
속성 이름
매개변수 설명
유형
필수 입력
Authorization
계산 후 얻은 서명 문자열
String
XCosSecurityToken
획득한 임시 키의 sessionToken. 해당 header의 x-cos-security-token 필드
String
아니요

자격 증명 획득

인스턴스 자체 인증 자격 증명은 인스턴스 시 전달한 매개변수를 통해 어떻게 획득할지 통제할 수 있습니다. 획득 방법은 세 가지입니다.
1. 인스턴스화 시 SecretId, SecretKey를 전송합니다. 서명이 필요할 때마다 인스턴스 내부에서 계산합니다.
2. 인스턴스화 시 getAuthorization 콜백을 전송합니다. 서명이 필요할 때마다 해당 콜백으로 계산하고, 서명을 인스턴스로 반환합니다.
3. 인스턴스화 시 getSTS 콜백을 전송합니다. 임시 키가 필요할 때마다 해당 콜백을 통해 돌아가 인스턴스에 반환합니다. 요청할 때마다 인스턴스 내부에서 임시 키로 계산하여 서명을 얻습니다.
다음은 자주 사용하는 일부 인터페이스 예시입니다. 자세한 초기화 방법은 demo 예시를 참고하십시오.

버킷 생성하기

cos.putBucket({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
}, function (err, data) {
console.log(err || data);
});
주의:
미니프로그램에서 버킷을 생성해야 하지만 버킷 이름을 모르는 경우, 버킷 이름을 도메인 화이트리스트로 설정할 수 없지만 확장명으로 호출할 수 있습니다. 관련 처리 조치는 FAQ를 참고하십시오.

버킷 리스트 조회

cos.getService(function (err, data) {
console.log(data && data.Buckets);
});

객체 업로드

미니프로그램 업로드 인터페이스 wx.uploadFile은 POST 요청만 지원합니다. SDK 파일 업로드는 postObject 인터페이스를 사용해야 합니다. 미니프로그램에서 파일 업로드 인터페이스만 사용해야 하는 경우 SDK를 참고하지 않는 것을 권장합니다. 간단한 예시는 demo를 참고하십시오.
// 먼저 파일을 선택하고 임시 경로를 획득합니다.
wx.chooseImage({
count: 1, // 기본값: 9
sizeType: ['original'], // 원본 이미지 또는 압축 이미지를 지정할 수 있습니다. 기본값은 원본 이미지입니다.
sourceType: ['album', 'camera'], // 출처를 사진첩 또는 카메라로 지정할 수 있습니다. 기본값은 둘 다입니다.
success: function (res) {
var filePath = res.tempFiles[0].path;
var filename = filePath.substr(filePath.lastIndexOf('/') + 1);
cos.postObject({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Key: '타깃 경로/' + filename,
FilePath: filePath,
onProgress: function (info) {
console.log(JSON.stringify(info));
}
}, function (err, data) {
console.log(err || data);
});
}
});

객체 리스트 조회

cos.getBucket({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Prefix: 'exampledir/', // 여기서 열거한 파일 접두사를 전달합니다.
}, function (err, data) {
console.log(err || data.Contents);
});

객체 다운로드

주의:
이 인터페이스는 객체 콘텐츠를 가져오는 데 사용합니다. 브라우저에서 파일 다운로드 요청이 필요한 경우 cos.getObjectUrl을 통해 url을 획득하여 다시 브라우저 다운로드를 트리거할 수 있습니다. 자세한 내용은 사전 서명된 URL 문서를 참고하십시오.
cos.getObject({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Key: 'exampleobject.txt',
}, function (err, data) {
console.log(err || data.Body);
});

객체 삭제

cos.deleteObject({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Key: 'picture.jpg',
}, function (err, data) {
console.log(err || data);
});

도움말 및 지원

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

피드백