Message API reference

Overview

Samsung Cloud Platform에서 제공하는 Message Hub는 Email, SMS, Mobile Application Push Notification 채널로 메시지를 발송할 수 있습니다.
본 가이드에서는 Message Hub의 메시지 전송 API에 대한 설명 및 호출하는 방법을 제공합니다.

Message Hub 호출 절차

Message Hub API URL 주소는 운영환경과 Region에 따라 변경되어야 하며, 호출 구간에 따라 Public URL과 Private URL로 구분됩니다. 아래의 표에서 해당 운영환경과 Region 정보를 확인하십시오.

API 호출하기

AUTH PARAMS

Header Description

X-Scp-Access-Key   : 삼성 클라우드 플랫폼 포털에서 발급받은 Access Key
X-Scp-Signature    : 호출 API 요청을 Access Key와 매핑되는 Access Secret Key로 암호화한 서명. HMAC 암호화 알고리즘은 HmacSHA256 사용
X-Scp-Timestamp    : 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 정의합니다.
X-Scp-Client-Type  : Userapi 고정(대소문자 구분)
Content-Type       : application/json 명시

Signature 생성하기

• 메시지 전송 API를 통해 Message Hub를 호출하려면 “인증키” 인증 모드로 유효한 접근 허용 IP에서 “인증키"를 통해 인증해야 합니다.
• 요청으로부터 서명할 문자열을 생성하고 Access, Secret Key로 HmacSHA256 알고리즘으로 암호화 후 Base64로 인코딩합니다.
• 이 값을 X-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 = "POST"; // Method
    var url = "{url}"; // url (예: /v1/emails/{email_id}/send)
    var timestamp = Date.now(); // timestamp
    var accessKey = "{accessKey}"; // access key
    var secretKey = "{secretKey}"; // secret key
    var clientType = "Userapi"; // 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>

Message Hub API 호출 예시

Curl

curl -i -X POST
-H "X-Scp-Access-Key:2sd2gg=2agbdSD26svcD"
-H "X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
-H "X-Scp-Timestamp:1605290625682"
-H "X-Scp-Client-Type:Userapi"
-H "Content-Type:application/json"
--data '{"recipient_addresses": ["someone@example.com"], "title": "notification title", "body": "notification body"}'
'https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send'

Python

import requests

url = "https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send"
payload = {
   'recipient_addresses': ['someone@example.com'],
   'title': 'notification title',
   'body': 'notification body'
}
headers = {
  'X-Scp-Access-Key': '2sd2gg=2agbdSD26svcD',
  'X-Scp-Signature': 'fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=',
  'X-Scp-Timestamp': '1605290625682',
  'X-Scp-Client-Type': 'Userapi',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

if response.status_code == 204:
    return None
else:
    raise Exception(f"Failed to POST API: {response.status_code}, {response.text}")

Java

String apiUrl = "https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send";
String accessKey = "2sd2gg=2agbdSD26svcD";
String signature = "fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=";
String timestamp = "1605290625682";
String clientType = "Userapi";
String requestBody = "{\"recipient_addresses\":[\"someone@example.com\"],\"title\":\"notification title\",\"body\":\"notification body\"}";

public static void sendMessage(String apiUrl, String requestBody) throws IOException {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPost postRequest = new HttpPost(apiUrl);
        postRequest.addHeader("X-Scp-Access-Key", accessKey);
        postRequest.addHeader("X-Scp-Signature", signature);
        postRequest.addHeader("X-Scp-Timestamp", timestamp);
        postRequest.addHeader("X-Scp-Client-Type", clientType);
        postRequest.addHeader("Content-Type", "application/json");
        postRequest.setEntity(new StringEntity(requestBody, "UTF-8"));

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

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

Message Hub Message API

Message Hub는 채널별로 다음과 같은 메시지 전송 API를 제공합니다.

Email 발송

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/{email_id}/send

Description

등록된 발신 Email 리소스를 사용하여 수신자에게 Email을 발송합니다.

Path Parameters

Body Parameters

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "recipient_addresses": ["someone@example.com"],
  "title": "notification title",
  "body": "notification body"
}

Example HTTP response

204 Response

Phone Book SMS 발송

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/phones/{phone_id}/send

Description

등록된 발신 Phone 리소스를 사용하여 수신 전화번호로 SMS를 발송합니다.

Path Parameters

Body Parameters

수신자 번호 입력 형식

수신자 번호는 ITU-T E.164 형식을 따르며, + 접두 유무로 국내/국제 표기를 구분합니다.

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "recipients": ["01012345678", "+14155552671"],
  "text": "sms text"
}

Example HTTP response

204 Response

Push Application 발송

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/push-applications/{application_id}/send

Description

등록된 Push Application 리소스를 사용하여 디바이스 토큰으로 FCM HTTP v1 기반의 Push 메시지를 발송합니다.

Path Parameters

Body Parameters

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "tokens": ["fcm-device-token-1"],
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "priority": "high",
  "ttl": "3600s"
}

Example HTTP response

204 Response