Quick Start

이 문서는 오브젝트 스토리지 서비스용 Java SDK v2의 시작 방법과 주요 기능 사용에 대한 자세한 가이드를 제공합니다.

사전 준비

시스템에 Java가 설치되어 있어야 합니다. Java 1.7 이상을 권장합니다. java -version 명령어로 Java 버전을 확인할 수 있습니다.

샘플 코드

Java SDK Rest v2는 다음과 같은 다양한 샘플 프로그램을 제공합니다.

SDK 설치

작업을 수행하기 전에 Java SDK를 설치해야 합니다. SDK는 GitHub 에서 다운로드할 수 있습니다.

Maven 프로젝트에 의존성 추가

<dependency>
  <groupId>com.chinanetcenter.wcs.sdk</groupId>
  <artifactId>wcs-java-sdk-v2</artifactId>
  <version>1.0.3</version>
</dependency>

IntelliJ IDEA에서 JAR 파일 import

1. Java SDK 패키지를 다운로드합니다.
2. 패키지를 압축 해제합니다.
3. wcs-java-sdk-rest-v2-1.0.0.jar 파일과 lib 디렉토리의 모든 JAR 파일을 프로젝트에 복사합니다.
4. IntelliJ IDEA에서 프로젝트를 선택한 후 File -> Project Structure -> Modules -> Dependencies -> + -> JARs or directories로 이동합니다.
5. 복사한 모든 JAR 파일을 선택하여 외부 라이브러리에 추가합니다.

초기화

WosClient는 버킷 및 오브젝트 관리를 위한 Java 클라이언트입니다. Java SDK를 사용하기 전에 WosConfiguration을 초기화하고 필요시 기본 설정을 조정해야 합니다.

// Access Key(ak), Secret Key(sk)는 콘솔의 유저 센터 > 내 정보 > AccessKey 관리에서 확인
// endpoint, regionName은 콘솔의 오브젝트 스토리지 > 버킷 개요에서 확인
String endPoint = "https://your-endpoint";
String regionName = "your regionName";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

WosConfiguration config = new WosConfiguration();
config.setSocketTimeout(30000);
config.setConnectionTimeout(10000);
config.setEndPoint(endPoint);
config.setRegionName(regionName);

// WosClient 인스턴스 생성
WosClient wosClient = new WosClient(ak, sk, config);
        
// wosClient 종료
wosClient.close();

WosClient 생성

// WosClient 인스턴스 생성
WosClient wosClient = new WosClient(ak, sk, config, regionName);

// wosClient 종료
wosClient.close();

참고: WosClient를 생성할 때 Endpoint 지정이 필수입니다. 프로젝트 내에서 하나 이상의 WosClient 인스턴스를 생성할 수 있습니다. WosClient는 스레드 세이프하며, 동시에 여러 요청을 처리할 수 있습니다.

WosClient 설정

WosConfiguration을 통해 WosClient를 설정할 수 있으며, 타임아웃/최대 연결 수 등 다양한 파라미터를 지원합니다. 주요 옵션은 다음과 같습니다.

빠른 시작

Java SDK로 다음의 대표적인 작업을 지원합니다:

1. 오브젝트 업로드

아래 코드는 오브젝트 업로드 방법을 보여줍니다.

wosClient.putObject("bucketname", "objectname", new ByteArrayInputStream("Hello WOS".getBytes()));

2. 오브젝트 다운로드

아래 코드는 오브젝트 내용을 다운로드하는 방법입니다.

WosObject wosObject = wosClient.getObject("bucketname", "objectname");
InputStream content = wosObject.getObjectContent();
if (content != null) {
    BufferedReader reader = new BufferedReader(new InputStreamReader(content));
    while (true) {
        String line = reader.readLine();
        if (line == null)
            break;
        System.out.println("\n" + line);
    }
    reader.close();
}

참고:

• wosObject.getObject로 오브젝트 내용 및 메타데이터가 포함된 WosObject 인스턴스를 얻을 수 있습니다.
• wosObject.getObjectContent로 InputStream을 얻어 읽을 수 있으며, 사용 완료 후 스트림을 닫아야 합니다.

3. 버킷 내 오브젝트 목록 조회

여러 오브젝트 업로드 후 버킷의 콘텐츠를 조회하려면 다음과 같이 할 수 있습니다.

ObjectListing objectListing = wosClient.listObjects("bucketname");
for (WosObject wosObject : objectListing.getObjects()) {
    System.out.println(" - " + wosObject.getObjectKey() + "  " +  "(size = " + wosObject.getMetadata().getContentLength() + ")");
}

참고:

• wosClient.listObjects는 ObjectListing 인스턴스를 반환합니다. 이를 통해 ObjectListing.getObjects로 오브젝트 목록에 접근할 수 있습니다.
• 기본적으로 최대 1,000개의 결과가 반환됩니다.

4. 오브젝트 삭제

오브젝트를 삭제하려면 다음과 같이 호출합니다.

wosClient.deleteObject("bucketname", "objectname");

5. 서명된 URL로 오브젝트 접근

오브젝트에 접근하기 위한 서명된 URL을 생성하는 예시는 다음과 같습니다.

TemporarySignatureRequest req = new TemporarySignatureRequest(HttpMethodEnum.GET, 300);
req.setBucketName(bucketName);
req.setObjectKey(objectKey);
TemporarySignatureResponse res = wosClient.createTemporarySignature(req);
System.out.println("Getting object using temporary signature URL:");
System.out.println("\t" + res.getSignedUrl());

6. WOS Client의 일반적인 사용 패턴

API 호출 후 예외가 발생하지 않으면 결과가 유효하며, 반환 객체는 기본 SDK 응답 클래스거나 그 하위 클래스입니다. 예외가 발생하면 SDK의 커스텀 예외 객체에서 오류 정보를 확인하세요.

아래 코드는 WOS Client의 일반적인 사용 예시입니다.

// 프로젝트 내에서 전역 WosClient 인스턴스를 하나만 유지할 수 있습니다.
// WosClient는 스레드 세이프하며 동시 사용을 지원합니다.
WosClient wosClient = null; 
try {
    String endPoint = "https://your-endpoint";
    String regionName = "your regionName";
    String ak = "*** Provide your Access Key ***";
    String sk = "*** Provide your Secret Key ***";

    // config 생성
    WosConfiguration config = new WosConfiguration();
    config.setSocketTimeout(30000);
    config.setConnectionTimeout(10000);
    config.setEndPoint(endPoint);
    config.setRegionName(regionName);

    // WosClient 인스턴스 생성
    wosClient = new WosClient(ak, sk, config);
    // 예시: 파일 업로드 API 호출
    HeaderResponse response = wosClient.putObject("bucketname", "objectname", new File("localfile"));  // 'localfile'은 업로드할 파일의 경로로, 전체 파일명을 입력하세요.
    System.out.println(response);
} catch (WosException e) {
    System.out.println("HTTP Code: " + e.getResponseCode());
    System.out.println("Error Code: " + e.getErrorCode());
    System.out.println("Error Message: " + e.getErrorMessage());
    System.out.println("Request ID: " + e.getErrorRequestId());
    System.out.println("Host ID: " + e.getErrorHostId());
} finally {
    // WosClient 인스턴스 종료. 전역 WosClient를 사용하는 경우, 매 API 호출 후 매번 종료할 필요는 없습니다.
    // wosClient.close() 호출 후 인스턴스를 재사용하면 안 됩니다.
    if (wosClient != null) {
        try {
            // wosClient.close();
        } catch (IOException e) {
            // 필요시 예외 처리
        }
    }
}