NAVER CLOUD PLATFORM API

개요

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

본 페이지에서는 NAVER CLOUD PLATFORM API 대한 간략한 설명 및 API 호출하는 방법을 제공합니다.
API는 RESTful API 방식으로 제공되며, XML와 JSON 형식으로 응답합니다. 액션에 따라 파라미터 값을 입력하고 등록, 수정, 삭제, 조회할 수 있으며, 서비스 및 운영 도구 자동화에 활용할 수 있습니다. HTTP 방식의 GET/POST 메서드 호출을 통해서 사용됩니다.

만일 호출이 잘못되었을 경우는 오류 코드와 메시지를 리턴합니다.

NAVER CLOUD PLATFORM API 호출은 다음과 같은 단계로 진행되어야 합니다.
1. 인증키 생성하기
2. API 호출하기
3. 응답 처리하기
4. 오류 처리하기

인증키 생성하기

NAVER CLOUD PLATFORM 계정이 생성되면 기본적으로 NAVER CLOUD PLATFORM API 인증키가 한개 발급됩니다. 발급된 인증키는 네이버 클라우드 플랫폼 홈페이지[마이페이지] > [계정관리] > [인증키관리]에서 확인할 수 있습니다. 인증키는 계정 생성 시 자동으로 발급되는 것 외에 사용자가 하나 더 생성할 수 있어서 두 개까지 발급받을 수 있습니다.

참고
인증키를 ‘사용 중지’로 설정하거나 삭제하면 유효하지 않은 키로 인식됩니다.


API 인증키는 Access Key와 Secret Key 한 쌍으로 구성되어 있습니다. 한 쌍의 API 인증키는 API를 인증할 때 파라미터로 직접 전달됩니다.

  1. 네이버 클라우드 플랫폼 홈페이지에서 로그인을 합니다.
  2. [마이페이지] > [계정관리] > [인증키관리] 메뉴로 접속하시면 “신규 API 인증키 생성” 버튼을 클릭합니다.
    • 기존에 생성하신 인증키가 있으실 경우에는 해당 인증키를 사용하실 수 있습니다.
  3. API 인증키 관리에서 발급받은 자신의 Access Key ID와 Secret Key를 확인합니다.

API 호출하기

AUTHPARAMS

Header Description
x-ncp-apigw-timestamp * 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것이다.
* API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-iam-access-key * 네이버 클라우드 플랫폼 포털 또는 Sub Account에서 발급받은 Access Key ID
x-ncp-apigw-signature-v2 * 위 예제의 Body를 Access Key ID와 맵핑되는 Secret Key로 암호화한 서명
* HMAC 암호화 알고리즘은 HmacSHA256 사용
  • AUTHPARAMS 요청 예시

    curl -i -X GET \
    -H "x-ncp-apigw-timestamp:1505290625682" \
    -H "x-ncp-iam-access-key:D78BB444D6D3C84CA38D" \
    -H "x-ncp-apigw-signature-v2:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEa=" \
    'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'
    
  • Signature 생성하기

    • 개행문자는 \n을 사용합니다.
    • 요청에 맞게 StringToSign을 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다.
    • 이 값을 x-ncp-apigw-signature-v2로 사용합니다.
요청 StringToSign
GET /photos/puppy.jpg?query1=&query2
x-ncp-apigw-timestamp={timestamp}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v2={signature}
GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{accessKey}
  • 요청 예시
public String makeSignature() {
	String space = " ";					// one space
	String newLine = "\n";					// new line
	String method = "GET";					// method
	String url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	String timestamp = "{timestamp}";			// current timestamp (epoch)
	String accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	String secretKey = "{secretKey}";

	String message = new StringBuilder()
		.append(method)
		.append(space)
		.append(url)
		.append(newLine)
		.append(timestamp)
		.append(newLine)
		.append(accessKey)
		.toString();

	SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
	Mac mac = Mac.getInstance("HmacSHA256");
	mac.init(signingKey);

	byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));
	String encodeBase64String = Base64.encodeBase64String(rawHmac);

  return encodeBase64String;
}
/*
https://code.google.com/archive/p/crypto-js/
https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/crypto-js/CryptoJS%20v3.1.2.zip
*/

/*
CryptoJS v3.1.2
code.google.com/p/crypto-js
(c) 2009-2013 by Jeff Mott. All rights reserved.
code.google.com/p/crypto-js/wiki/License
*/
<script type="text/javascript" src="./CryptoJS/rollups/hmac-sha256.js"></script>
<script type="text/javascript" src="./CryptoJS/components/enc-base64.js"></script>

function makeSignature() {
	var space = " ";				// one space
	var newLine = "\n";				// new line
	var method = "GET";				// method
	var url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	var timestamp = "{timestamp}";			// current timestamp (epoch)
	var accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	var secretKey = "{secretKey}";			// secret key (from portal or Sub Account)

	var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey);
	hmac.update(method);
	hmac.update(space);
	hmac.update(url);
	hmac.update(newLine);
	hmac.update(timestamp);
	hmac.update(newLine);
	hmac.update(accessKey);

	var hash = hmac.finalize();

	return hash.toString(CryptoJS.enc.Base64);
}
import sys
import os
import hashlib
import hmac
import base64
import requests
import time

def	make_signature():
	timestamp = int(time.time() * 1000)
	timestamp = str(timestamp)

	access_key = "{accessKey}"				# access key id (from portal or Sub Account)
	secret_key = "{secretKey}"				# secret key (from portal or Sub Account)
	secret_key = bytes(secret_key, 'UTF-8')

	method = "GET"
	uri = "/photos/puppy.jpg?query1=&query2"

	message = method + " " + uri + "\n" + timestamp + "\n"
	+ access_key
	message = bytes(message, 'UTF-8')
	signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
	return signingKey
function makeSignature() {
	nl=$'\\n'

	TIMESTAMP=$(echo $(($(date +%s%N)/1000000)))
	ACCESSKEY="{accessKey}"				# access key id (from portal or Sub Account)
	SECRETKEY="{secretKey}"				# secret key (from portal or Sub Account)

	METHOD="GET"
	URI="/photos/puppy.jpg?query1=&query2"

	SIG="$METHOD"' '"$URI"${nl}
	SIG+="$TIMESTAMP"${nl}
	SIG+="$ACCESSKEY"

	SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}

응답 처리하기

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

오류 처리하기

  • 상품 API 호출에 대한 오류 코드는 각 상품의 해당 가이드(API 참조서)를 참고하세요.

공통 오류 코드

  • 요청 파라미터가 Contenct-type:application/json일 때(default)

    {
    "error":{
      "errorCode":"210",
      "message":"Permission Denied"
    }
    }
    
  • 요청 파라미터가 Contenct-type:application/xml일 때

    <?xml version='1.0' encoding='UTF-8' ?>
    <Message>
    <error>
        <errorCode>210</errorCode>
        <message>Permission Denied</message>
    </error>
    </Message>
    
HTTP 상태 코드 오류 코드 오류 메시지 설명
400 100 Bad Request Exception protocol(https), endocing(UTF-8) 등 Request 오류
401 200 Authentication Failed 인증 실패
401 210 Permission Denied 권한 없음
404 300 Not Found Exception 권한 없음
429 400 Quota Exceeded Quota 초과
429 410 Throttle Limited Rate 초과
429 420 Rate Limited Rate 초과
413 430 Request Entity Too Large 요청 엔티티 크기 초과
503 500 Endpoint Error 엔드포인트 연결 오류
504 510 Endpoint Timeout 엔드포인트 연결 시간 초과
500 900 Unexpected Error 예외 처리가 안된 오류

지원 API 및 SDK

본 NAVER CLOUD PLATFORM API는 Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation, Hash Filter 등의 다양한 기능을 API로 제어할 수 있습니다. API는 RESTful API 방식으로 제공되며, XML, JSON 형식으로 응답합니다. 액션에 따라 파라미터 값을 입력하고 등록, 수정, 삭제, 조회할 수 있으며, 서비스 및 운영 도구 자동화에 활용할 수 있습니다.

상품 API SDK
Server Server API ncloud_server.zip
Load Balancer Load Balancer API ncloud_loadbalancer.zip
Auto Scaling Auto Scaling API ncloud_autoscaling.zip
Monitoring Monitoring API ncloud_monitoring.zip
Security Security API ncloud_security.zip
GeoLocation GeoLocation API ncloud_geolocation.zip
CDN+ CDN+ API ncloud_cdn.zip
    Cloud DB Cloud DB API ncloud_clouddb_v2.zip
    Cloud Outbound Mailer Cloud Outbound Mailer API ncloud_outboundmailer.zip

Ncloud API 릴리즈 노트

네이버 클라우드 플랫폼의 Ncloud APIs는 서비스 출시 이후에도 다양한 개선 작업을 통해 제공되고 있습니다.

Ncloud APIs 제공 버전 안내

네이버 클라우드 플랫폼에서는 현재 3가지 버전의 서비스들을 제공하고 있습니다: Ncloud APIs Old, Ncloud APIs V1, Ncloud APIs V2
사용성이 향상된 Ncloud APIs V2 버전의 호출을 권장 드리며, Ncloud APIs Old와 Ncloud APIs V1 버전은 안내 기간을 거쳐 사용이 중지될 예정입니다.

  • Ncloud APIs Old

    네이버 클라우드 플랫폼 초기에 제공하였던 https://api.ncloud.com/ 도메인으로 시작하는 API입니다. Ncloud APIs Old 버전은 OAuth 인증 방식을 사용합니다.
  • Ncloud APIs V1

    API 관리 기능이 향상된 새로운 API Gateway를 통해 https://ncloud.apigw.ntruss.com/ 도메인으로 시작하는 API입니다. Ncloud APIs V1 버전부터는 API Gateway에서 발급한 API Key를 통한 인증 방식을 제공합니다.

    Ncloud APIs V1을 호출할 때는 API Gateway에서 발급한 API key가 필요하며 이를 위해 API Gateway 서비스 신청이 필요합니다.(단, API key만 발급되기 때문에 API Gateway에 대한 과금은 발생하지 않습니다. )

  • Ncloud APIs V2

    Ncloud APIs V2는 API key가 필요없는 방식으로 오퍼레이션 및 호출 방식은 Ncloud APIs V1과 동일하나, API Gateway 신청이 필요없어 편리합니다.

    상품별로 API Key를 필수로 적용해야 하는 경우가 있으므로, API Key의 사용여부는 각 상품의 지원 API 명세를 따릅니다.

Ncloud API 인증방식

  1. OAuth 인증방식

    • Ncloud APIs Old 버전에서 사용하는 방식이며, 별도의 시스템이 해당 로그인 정보를 저장하지 않고 암호화된 인증 토큰을 이용해야만 리소스에 접근할 수 있도록 허용합니다.
  2. API Key 인증방식

    • API Key 인증방식은 계정별 Key를 발급받아 인증에 활용하는 방식입니다. API Key는 네이버 클라우드 플랫폼 콘솔의 API Gateway > API Key에서 “API Key 생성” 메뉴를 통해서 API Key를 생성할 수 있습니다.

    • Ncloud APIs V1의 경우에는 호출시 API Key를 인증과 호출시 헤더에 반드시 포함해야 합니다.

    • Ncloud APIs V2의 경우에는 호출시 API Key를 인증이나 호출시 헤더에 포함할 필요가 없습니다.

이전 버전 가이드 바로 가기

상품 Ncloud APIs OLD : (OAuth 인증) Ncloud APIs V1 : (API Key 인증) Ncloud APIs V2 : (API Key 인증 안함)
Server 바로가기 바로가기 Server API
Load Balancer 바로가기 바로가기 Load Balancer API
Auto Scaling 바로가기 바로가기 Auto Scaling API
Monitoring 바로가기 바로가기 Monitoring API
Security 바로가기 바로가기 Security API
GeoLocation 바로가기 바로가기 GeoLocation API
CDN 바로가기 바로가기 CDN API
Global CDN 바로가기 바로가기 CDN API
Cloud DB 제공 안함 바로가기 Cloud DB API
Cloud Outbound Mailer 제공안함 바로가기 Cloud Outbound Mailer API

(상품별로 API Key를 필수로 적용해야 하는 경우가 있으니, API Key의 사용여부는 각 상품의 지원 API에서 확인합니다.)

Ncloud APIs Fade out 주요 일정

  • Ncloud APIs V1는 2019년 12월 31일에 서비스가 종료되며, 2020년 1월 1일 이후 서비스 이용이 불가능합니다.
  • Ncloud APIs OLD는 2019년 6월 30일에 서비스가 종료되며, 2019년 6월 30일 이후 서비스 이용이 불가능합니다.