Common

Overview

삼성 클라우드 플랫폼에서 제공하는 인프라/솔루션 상품을 이용할 수있도록 지원하는 응용 프로그램 인터페이스(Application Programming Interface, API)를 제공하고 있습니다.

본 가이드에서는 삼성 클라우드 플랫폼 Open API에 대한 간략한 설명 및 API 호출하는 방법을 제공합니다.

API는 RESTful API 방식으로 제공되며, JSON 형식으로 응답합니다.

API에 따라 파라미터 값을 입력하고 등록, 수정, 삭제 , 조회 할 수 있습니다.

HTTP 방식의 POST/GET/PUT/DELETE 메서드 호출을 통해서 사용합니다.

호출 실패 시 오류 코드와 메시지를 리턴합니다.

API 버저닝

OpenAPI는 Micro version 형태의 API 버전을 지원하며 각 상품의 endpoint api를 호출하여 상품의 api 버전을 확인 할 수 있습니다.

지원하는 버전에 맞춰 api 호출에 Scp-Api-Version 헤더를 설정하면, 해당 버전의 api를 호출 할 수 있습니다.

헤더에 해당 정보가 없을 경우 현재 상품이 지원하는 최신 current 버전이 호출되며 버전 업데이트에 따라 호출하는 버전에 따라 req/res가 바뀔 수 있습니다.

API 버전 Status 목록

API 버전확인 api 호출예시

https://iam.s.samsungsdscloud.com/

API 버전 api 응답 예시

{
  "versions": [
    {
      "id": "v1.0",
      "links": [
        {
          "href": "http://iam.s.samsungsdscloud.com/v1",
          "rel": "self"
        }
      ],
      "not_before": "2026-02-23",
      "status": "CURRENT"
    }
  ]
}

삼성 클라우드 플랫폼 Open API 호출 절차

SCP OpenAPI URL주소는 운영환경과 Region에 따라 변경되어야 합니다. 아래의 표에서 해당 운영환경과 Region 정보를 확인하십시오.

인증키 생성하기

삼성 클라우드 플랫폼의 Open API 기능을 사용하시려면 인증키를 발급받아야 합니다.

인증키 발급은 삼성 클라우드 플랫폼 콘솔의 [My 메뉴] > [My Info] > [인증키 관리] 에서 확인 할 수 있습니다.

인증키는 Access Key와 Access Secret Key의 한 쌍으로 구성되어 있습니다. 인증키는 API 인증 토큰을 발급할 때 사용됩니다.

1. Samsung Cloud Platform Console에 로그인을 하세요.
2. My 메뉴 > My Info > 인증키 관리 메뉴로 이동하여, 인증키 생성 버튼을 클릭하세요.
3. 기간과 사용 용도를 작성하고, 확인 버튼을 클릭하여 인증키를 생성하세요.
4. 인증키 목록에서 발급받은 Access Key와 Access Secret Key를 확인하세요.
   • Access Secret Key는 인증키 상세 페이지에서 확인할 수 있습니다.

임시 보안 자격 증명 (Optional)

임시 보안 자격 증명은 사용자가 정해진 시간 동안만 유효한 인증 정보를 통해 시스템에 접근할 수 있도록 하는 기능입니다. 이 자격 증명은 일반적으로 다음과 같은 목적을 위해 사용됩니다:

• 보안 강화: 장기 자격 증명(예: API 키, 비밀번호) 유출 시의 피해를 줄이기 위해
• 권한 위임: 외부 사용자나 시스템에 제한된 권한을 임시로 부여 가능
• 자동 만료: 자격 증명이 일정 시간 후 자동으로 만료되므로 관리가 간편

구성 요소

임시 자격 증명은 일반적으로 다음 정보를 포함합니다:

1. Access Key : 인증을 위한 식별자
2. Secret Key : 암호화된 인증 서명 생성에 사용
3. Session Token: 세션 식별 및 유효성 검사를 위한 토큰

임시 보안 자격 증명 생성하기

삼성 클라우드 플랫폼의 임시 보안 자격 증명 기능을 사용하시려면 역할을 생성하여야 합니다.

역할 생성은 삼성 클라우드 플랫폼 콘솔의 [My 메뉴] > [My Info] > [역할] 에서 확인 할 수 있습니다.

• 수행 주체

  • 역할을 생성할시 해당 역할을 맡을 수 있는 수행 주체를 설정해 주어야 합니다.
  • 수행 주체는 역할을 맡을 수 있는 계정, 사용자 SRN, 자격 증명 공급자 등으로 지정합니다

• 정책

  • 역할을 맡은 사람이 어떤 행동을 할 수 있는지 정의하는 정책을 설정해주어야 합니다.
  • 정책은 최소 권한 원칙(Principle of Least Privilege)을 준수하여 필요한 권한만 부여합니다

1. Samsung Cloud Platform Console에 로그인을 하세요.
2. My 메뉴 > My Info > 역할 메뉴로 이동하여, 역할 생성 버튼을 클릭하세요.
3. 역할명을 작성하고 최대 세션 지속 시간을 선택하여 역할 수임의 유효시간을 설정하세요.
4. 수행 주체 항목에서 구분 버튼을 눌러 수행 주체를 설정할 수 있으며, 추가 버튼을 눌러 여러 수행 주체 설정이 가능합니다
5. 정책의 목록에서 원하는 정책을 확인한 후 왼쪽의 체크박스을 누르면 정책의 설정이 가능합니다
6. 완료 버튼을 눌러 역할의 생성을 확인합니다

이후엔 역할자의 토큰을 생성해주어야 합니다. 이는 assume-role api를 수행하여야 하며, 결과 값으로는 Access key, Secret key, Session token을 받게 됩니다

assume-role 사용법 문서 : assume-role 사용법

API 호출하기

AUTH PARAMS

Header Description

Scp-Accesskey      : 삼성 클라우드 플랫폼 포털에서 발급받은 Access Key 혹은 임시 보안 자격 증명의 임시 Access key
Scp-Signature      : 호출 API 요청을 Access Key와 매핑되는 Access Secret Key로 암호화한 서명. HMAC 암호화 알고리즘은 HmacSHA256 사용
Scp-Timestamp      : 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 정의합니다.
Scp-ClientType     : Client Type
Scp-Session-Token (Optional) : 임시 보안 자격 증명의 세션 토큰

LANGUAGE PARAMS

Open API 실행 시 사용할 언어는 요청 헤더에 Accept-Language로 설정해야 합니다.

Header Description

Accept-Language : API 실행 시 사용할 언어를 설정 (미 입력 시 영어 사용)
                  한국어    : ko-KR
                  영어      : en-US
                  
Scp-Api-Version : openapi 호출시 microversion에 대한 헤더가 입력되야합니다.
                  헤더에 해당 정보가 없을 경우 현재 상품이 지원하는 최신 current 버전이 호출되며
                  호출하는 버전에 따라 req/res가 바뀔 수 있습니다.
                  ex. {상품 명} 1.0 -> sample 1.0

Signature 생성하기

• 요청으로부터 서명할 문자열을 생성하고 Access, Secret Key로 HmacSHA256 알고리즘으로 암호화 후 Base64로 인코딩합니다.
• 이 값을 Scp-Signature로 사용합니다.
• 생성된 Signature는 15분간 유효합니다.

Signature 생성 Sample Code (Java)

public static String makeHmacSignature(String method,
                                       String url,
                                       String timestamp,
                                       String accessKey,
                                       String accessSecretKey,
                                       String clientType) {
 
    String body = method + url + timestamp + accessKey + clientType;
 
    String encodeBase64Str;
 
    try {
        byte[] message = body.getBytes("UTF-8");
        byte[] secretKey = accessSecretKey.getBytes("UTF-8");
 
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacSha256 = mac.doFinal(message);
        encodeBase64Str = Base64.getEncoder().encodeToString(hmacSha256);
    } catch (Exception e) {
        throw new RuntimeException("Failed to calculate hmac-sha256", e);
    }
 
    return encodeBase64Str;
}

Signature 생성 Sample Code (JavaScript)

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/enc-base64-min.js"></script>
<script type="text/javascript">
function makeSignature() {
    var method = "GET"; // Method
    var url = "{url}"; // url
    var timestamp = Date.now(); // timestamp
    var accessKey = "{accessKey}"; // access key
    var secretKey = "{secretKey}"; // secret key
    var clientType= "{clientType}"; // client type
 
    url = encodeURI(url); // 한글, 특수 문자 처리
 
    var message = method + url + timestamp + accessKey + clientType;
 
    var hash = CryptoJS.HmacSHA256(message, secretKey);
    return CryptoJS.enc.Base64.stringify(hash);
}
</script>

Open API 호출 예시

Curl

curl -i -X GET
-H "Scp-Accesskey:2sd2gg=2agbdSD26svcD"
-H "Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
-H "Scp-Timestamp:1605290625682"
-H "Scp-ClientType:Openapi"
-H "Accept-Language:ko-KR"
-H "Scp-Api-Version: sample 1.0"
(Optional) -H "Scp-Session-Token: AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t..."
'https://support.{env}.samsungsdscloud.com/v1/notices'

Python

import requests

url = "https://support.{env}.samsungsdscloud.com/v1/notices"
payload = {}
headers = {
  'Scp-Accesskey': '2sd2gg=2agbdSD26svcD',
  'Scp-Signature': 'fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=',
  'Scp-Timestamp': '1605290625682',
  'Scp-ClientType': 'Openapi',
  'Accept-Language': 'ko-KR',
  'Scp-Api-Version': 'sample 1.0',
  # (Optional)
  'Scp-Session-Token': 'AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t...'
}

response = requests.request("GET", url, headers=headers, data=payload)

if response.status_code == 200:
    contents = response.text
    return contents
else:
    raise Exception(f"Failed to GET API: {response.status_code}, {response.text}")

Java

String apiUrl = "https://support.{env}.samsungsdscloud.com/v1/notices";
String language = "ko-KR";
String accessKey = "2sd2gg=2agbdSD26svcD"
String signature = "fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
String timestamp = "1605290625682"
String clientType = "Openapi"
String apiVersion = "sample 1.0"
String sessionToken = "AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t..."

public static String getAPI(String token, String apiUrl, String language) throws IOException {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpGet getRequest = new HttpGet(apiUrl);
        getRequest.addHeader("Scp-Accesskey", accessKey);
        getRequest.addHeader("Scp-Signature", signature);
        getRequest.addHeader("Scp-Timestamp", timestamp);
        getRequest.addHeader("Scp-ClientType", clientType);
        getRequest.addHeader("Accept-Language", language);
        getRequest.addHeader("Scp-Api-Version", apiVersion);
        // (Optional)
        getRequest.addHeader("Scp-Session-Token", sessionToken);

        HttpResponse response = httpClient.execute(getRequest);
        int statusCode = response.getStatusLine().getStatusCode();

        if (statusCode == 200) {
            String responseBody = EntityUtils.toString(response.getEntity());
            httpClient.close();
            return responseBody;
        } else {
            String responseBody = EntityUtils.toString(response.getEntity());
            httpClient.close();
            throw new RuntimeException("Failed to Request: " + statusCode + ", " + responseBody);
        }
    }

응답

* 상품의 API 호출에 대한 응답은 각 상품의 해당 가이드(API 참조서)를 참고하세요. 

공통 오류 코드

공통 오류 응답 값

{
    "errors": [
        {
            "request_id": "req-aca5442b21eb46d89e4740f529ecbc6e",
            "global_request_id": "req-c79a747b-a50e-434d-a6f2-90aa7d06c1ea",
            "code": "extension.api.server-error",
            "status": 404,
            "title": "Not Found",
            "detail": "No Notice found with ID d34f74a2dfc244e0bba141fd667475ad",
            "related_resources": [],
            "links": [],
            "response": {}
        }
    ]
}

공통 오류 상태 코드