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

Java SDK

포커스 모드
폰트 크기
마지막 업데이트 시간: 2025-11-13 16:25:20

클라이언트 네트워크는 정상인데 HTTP로 COS 액세스가 굉장히 느리거나 Connection reset 오류가 발생합니다. 어떻게 처리해야 하나요?

일부 지역 ISP에서 COS 도메인을 하이재킹했을 수 있습니다. 최대한 HTTPS를 사용해 COS에 액세스하시기 바랍니다.

SDK 실행 후 java.lang.NoSuchMethodError 오류가 발생합니다. 어떻게 처리해야 하나요?

원인: 일반적으로 JAR 패키지 충돌이 발생했기 때문입니다. 예를 들어 사용자가 작업하는 httpclient 라이브러리의 JAR 패키지 버전은 A 방법이 없는데 SDK에 종속된 JAR 패키지가 A 방법을 사용하는 경우입니다. 이로 인해 실행 시 로딩 순서에 문제가 생기고, 사용자 프로그램의 httpclient 라이브러리가 로딩되어 NoSuchMethodError 오류가 발생하게 됩니다. 해결 방법: 방법1: 프로그램 중 NoSuchMethodError 오류를 일으키는 패키지 버전을 SDK pom.xml 내의 해당 라이브러리의 버전과 일치하도록 변경하십시오. 방법2: cos-java-sdk를 cos_api-bundle로 변경합니다. 이 방법은 cos-java-sdk의 모든 종속을 독립적으로 설치하여 더 많은 용량을 차지합니다.
<groupId>com.qcloud</groupId>
<artifactId>cos_api-bundle</artifactId>
<version>5.6.35</version>

Java SDK의 기본 타임아웃 시간은 얼마나 되나요?

Java SDK의 기본 연결 타임아웃 시간은 45000ms이며, 기본 읽기/쓰기 타임아웃 시간은 45000ms입니다. SDK의 SetConnectionTimeoutMs 방법과 SetReadWriteTimeoutMs 방법을 사용해 변경할 수 있습니다.

Java SDK 업로드 속도가 느리고 로그에서 IOException이 빈번하게 출력됩니다. 어떻게 처리해야 하나요?

원인과 해결 방법은 다음과 같습니다.
1. 먼저 공용 네트워크로 COS에 액세스하지 않았는지 확인합니다. 현재 동일 리전 내 CVM은 내부 네트워크로 COS에 액세스합니다. 내부 네트워크가 리졸브되는 IP 대역은 10, 100, 169입니다. COS 도메인과 관련된 자세한 내용은 리전 및 액세스 도메인을 참고하십시오. 공용 네트워크로 내보내는 대역폭이 좁지 않은지 또는 다른 프로그램이 대역폭 리소스를 점유하고 있지 않은지 확인하십시오.
2. 생성 환경의 로그 레벨이 DEBUG가 아닌지 확인하십시오. INFO 로그 사용을 권장합니다.
3. 현재 간편 업로드의 속도는 10MB에 달하며, 고급 API로 32개를 동시 업로드를 하는 경우 60MB에 달합니다. 만약 속도가 이 두 값보다 훨씬 낮다면 위의 두 사항을 참고하십시오.
4. WARN 로그에서 IOException이 출력되면 SDK가 재시작되므로 무시해도 됩니다. IOException의 원인이 너무 느린 네트워크 속도 때문이라면 해결 방법 1과 2를 참고하십시오.

파일 업로드 요청 경로에 '+'가 있으면 Code: 403 SignatureDoesNotMatch 오류가 발생합니다. 어떻게 처리해야 하나요?

예상 원인: 사용자 Java 환경의 httpclient 버전으로 인한 urlencode 인코딩 오류일 수 있습니다. 해결 방법: 다음 방법을 통해 해결하는 것을 권장합니다. 방법1: httpclient 4.5.3 버전 사용
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>4.5.3</version>
방법2: cos-java-sdk를 cos_api-bundle로 변경합니다. 이 방법은 cos-java-sdk의 모든 종속을 독립적으로 설치하여 더 많은 용량을 차지합니다.
<groupId>com.qcloud</groupId>
<artifactId>cos_api-bundle</artifactId>
<version>5.6.35</version>

Java SDK 사용 시 특정 종속 버전이 너무 낮다고 안내되며 오류가 발생합니다. 어떻게 처리해야 하나요?

원인: 사용자의 Java 환경 종속 버전과 Java SDK에서 필요한 종속 버전에 충돌이 발생한 경우일 수 있습니다. 해결 방법: 방법1: 안내에 따라 해당 종속을 필요한 버전으로 업데이트하십시오. 방법2: cos-java-sdk를 cos_api-bundle로 변경합니다. 이 방법은 cos-java-sdk의 모든 종속을 독립적으로 설치하여 더 많은 용량을 차지합니다.
<groupId>com.qcloud</groupId>
<artifactId>cos_api-bundle</artifactId>
<version>5.6.35</version>

SDK는 어떻게 디렉터리를 생성하나요?

COS에서 파일과 디렉터리는 모두 객체이며 디렉터리는 /로 끝나는 객체입니다. 파일 생성 시 디렉터리를 생성할 필요가 없습니다. 예를 들어 객체 키가 xxx/yyy/zzz.txt인 파일을 생성할 때는 key를 xxx/yyy/zzz.txt로 설정하면 되고 xxx/yyy/ 객체를 생성할 필요가 없습니다. 콘솔에서 표시할 때 /로 분리되어 디렉터리 계층적 효과를 나타내지만, 해당 디렉터리 객체는 존재하지 않습니다. 디렉터리 객체를 생성하려면 아래 예시 코드를 사용할 수 있습니다.
String bucketName = "examplebucket-1250000000";
String key = "folder/images/";
// 디렉터리 객체는 /로 끝나는 빈 파일이며, 길이가 0인 byte 스트림을 업로드함
InputStream input = new ByteArrayInputStream(new byte[0]);
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentLength(0);

PutObjectRequest putObjectRequest =
new PutObjectRequest(bucketName, key, input, objectMetadata);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);

SDK는 HTTPS를 어떻게 사용하나요?

SDK 관련 설정은 ClientConfig 클래스에 통합되어 있으며 예시 코드는 아래와 같습니다.
// 사용자의 개인 정보(secretId, secretKey) 초기화
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// bucket의 리전 설정. COS 리전의 약칭은 https://www.tencentcloud.com/document/product/436/6224 참고
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
// https 사용 설정
clientConfig.setHttpProtocol(HttpProtocol.https);
// cos 클라이언트 생성
COSClient cosClient = new COSClient(cred, clientConfig);

SDK는 프록시를 어떻게 사용하나요?

프록시로 COS 액세스가 필요한 클라이언트의 경우 ClientConfig 클래스에서 사용할 프록시 IP(혹은 도메인) 및 포트를 설정하십시오. 예시 코드는 아래와 같습니다.
// 사용자의 개인 정보(secretId, secretKey) 초기화
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// bucket의 리전 설정. COS 리전의 약칭은 https://www.tencentcloud.com/document/product/436/6224 참고
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
// 사용할 프록시 설정(IP와 포트를 함께 설정해야 함)
// 프록시 IP 설정(도메인 입력 가능)
clientConfig.setHttpProxyIp("192.168.2.3");
// 프록시 포트 설정
clientConfig.setHttpProxyPort(8080);
// cos 클라이언트 생성
COSClient cosClient = new COSClient(cred, clientConfig);

사용자 정의 EndpointBuilder는 어떻게 설정하나요?

시나리오에서 API가 요청한 Endpoint를 지정해야 할 수 있습니다. 이때 EndpointBuilder 인터페이스 내 buildGeneralApiEndpoint와 buildGetServiceApiEndpoint에서 두 가지 함수를 구현해야 하며, 각각 일반 API 요청과 GETService 요청에 대한 원격 Endpoint를 지정해야 합니다. 사용 예시는 아래와 같습니다.
// 1단계: EndpointBuilder 인터페이스의 두 가지 함수 구현
class SelfDefinedEndpointBuilder implements EndpointBuilder {
@Override
public String buildGeneralApiEndpoint(String bucketName) {
return String.format("%s.%s", bucketName, "mytest.com");
}

@Override
public String buildGetServiceApiEndpoint() {
return "service.mytest.com";
}
}

// 2단계: 클라이언트 초기화
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
SelfDefinedEndpointBuilder selfDefinedEndpointBuilder = new SelfDefinedEndpointBuilder();
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing"));
clientConfig .setEndpointBuilder(selfDefinedEndpointBuilder);
COSClient cosClient = new COSClient(cred, clientConfig);

SDK 업로드, 다운로드, 일괄 삭제 등의 작업 시 사용하는 key 값에 접두사 /를 추가해야 하나요?

COS의 key 값은 / 접두사가 필요 없습니다. 예를 들어 객체 key 값을 exampleobject로 업로드 객체로 설정하면 URL: http://cos.ap-guangzhou.myqcloud.com/exampleobject로 액세스할 수 있습니다.
주의:
일괄 삭제 요청 시 접두사 /로 시작하는 key를 넣지 마십시오. 객체 삭제에 실패할 수 있습니다.
COS Java SDK 구 버전은 예를 들어 125로 시작하는 APPID만 지원합니다. 만약 130으로 시작하는 APPID를 사용하는 경우 SDK를 최신 버전으로 업데이트하는 것을 권장합니다. Java SDK의 다운로드 및 설치는 Java SDK 문서를 참고하십시오.

COS Java SDK로 대용량 파일을 업로드하면 오류가 발생합니다. 어떻게 처리해야 하나요?

Java SDK로 5G를 초과하는 파일을 업로드하는 경우 고급 업로드 인터페이스 사용을 권장합니다. 고급 업로드 인터페이스는 사용자 파일의 크기와 데이터 유형에 따라 간편 업로드 또는 멀티파트 업로드 방식을 자동으로 선택합니다.

Java SDK에서 파일 업로드 진행률은 어떻게 확인하나요?

업로드 진행률을 확인하려면 고급 업로드 인터페이스 사용을 권장합니다. Upload의 getProgress() 방법을 호출하여 업로드 진행률인 TransferProgress 유형을 가져옵니다.

Java SDK는 로컬 파일의 CRC64 계산을 지원하나요?

COS Java SDK 자체는 로컬 파일의 crc64 계산을 지원하지 않으며, 사용자의 서비스에서 직접 구현해야 합니다. Java issues를 참고하여 방법을 확인하십시오.

Java SDK가 COS에서 반환된 CRC64가 21비트인지 확인하고, 로컬에서 계산된 CRC64와 비교하는 방법은 무엇입니까?

Java의 Long은 20자리 숫자만 지원합니다. 다음 비교 방식을 참고하십시오.
CRC64 localCRC = new CRC64();
// 로컬 crc64 계산
localCRC.update();
//...

// COS 가 반환한 CRC 를 Long으로 변환
cosCRC = crc64ToLong(strCOSCRC);

// 비교
if (cosCRC == localCRC.getValue()) {
xxx
}

// COS에서 반환된 CRC64를 1개 Java 내 Long으로 변환하는 데 사용
long crc64ToLong(String crc64) {
if (crc64.charAt(0) == '-') {
return negativeCrc64ToLong(crc64);
} else {
return positiveCrc64ToLong(crc64);
}
}

long positiveCrc64ToLong(String strCrc64) {
BigInteger crc64 = new BigInteger(strCrc64);
BigInteger maxLong = new BigInteger(Long.toString(Long.MAX_VALUE));

int maxCnt = 0;

while (crc64.compareTo(maxLong) > 0) {
crc64 = crc64.subtract(maxLong);
maxCnt++;
}

return crc64.longValue() + Long.MAX_VALUE * maxCnt;
}

long negativeCrc64ToLong(String strCrc64) {
BigInteger crc64 = new BigInteger(strCrc64);
BigInteger minLong = new BigInteger(Long.toString(Long.MIN_VALUE));

int minCnt = 0;

while (crc64.compareTo(minLong) < 0) {
crc64 = crc64.subtract(minLong);
minCnt++;
}

return crc64.longValue() + Long.MIN_VALUE * minCnt;
}

Java SDK에서 장기간 연결을 사용할 수 있나요?

Java SDK는 기본적으로 장기간 연결을 사용합니다.

Java SDK로 지정 디렉터리의 모든 경로를 어떻게 획득하나요? 경로가 파일인지 폴더인지 어떻게 판단하나요?

Java SDK의 객체 리스트 조회 기능으로 버킷에 있는 객체를 나열할 수 있으며, prefix 매개변수로 디렉터리 접두사를 지정할 수 있습니다.

도움말 및 지원

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

피드백