- 인쇄
- PDF
Ncloud API
- 인쇄
- PDF
Classic/VPC 환경에서 이용 가능합니다 .
NAVER Cloud Platform API(Ncloud API)의 지원 정보를 확인하고 API 공통 호출 및 인증 방법을 확인합니다.
지원 API 및 SDK
NAVER Cloud Platform API는 Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation, Hash Filter 등의 다양한 기능을 제어할 수 있습니다. 지원하는 API와 SDK 정보를 확인해 주십시오.
API
호환 API와 연동 API를 제외한 모든 API가 해당됩니다. 서비스별 지원하는 구체적인 API 목록은 서비스별 API 가이드에서 확인해 주십시오.
SDK
서비스별 지원하는 SDK 목록과 다운로드는 다음과 같습니다.
서비스 | SDK 다운로드 |
---|---|
Server | ncloud_server.zip |
Load Balancer | ncloud_loadbalancer.zip |
Auto Scaling | ncloud_autoscaling.zip |
Monitoring | ncloud_monitoring.zip |
Security | ncloud_security.zip |
GeoLocation | ncloud_geolocation.zip |
CDN+ | ncloud_cdn_v2.zip |
Cloud DB | ncloud_clouddb_v2.zip |
Cloud Outbound Mailer | 다운로드 |
API 호출
NAVER Cloud Platform API는 RESTful API 방식으로 제공되며, XML와 JSON 형식으로 응답합니다. 액션에 따라 파라미터 값을 입력하고 등록, 수정, 삭제, 조회할 수 있으며, 서비스 및 운영 도구 자동화에 활용할 수 있습니다. HTTP 방식의 GET/POST 메서드 호출을 통해서 사용되며 잘못된 호출 시 오류 코드와 메시지를 리턴합니다. NAVER Cloud Platform API 호출 단계는 다음과 같습니다.
1. 인증키 생성
NAVER Cloud Platform API를 사용하려면 우선 인증키를 생성해야 합니다. 인증키는 권한을 가진 사용자만 해당 API를 호출할 수 있도록 사용자를 식별하는 도구입니다. Access Key
와 Secret Key
의 한 쌍으로 구성되어 있으며, Access Key
와 Secret Key
는 API 인증 시 전달되는 파라미터로 사용됩니다.
NAVER Cloud Platform API 인증키는 네이버 클라우드 플랫폼 계정 생성 시 자동으로 1개가 생성됩니다. 자동 생성된 인증키 외에 사용자가 포털에서 직접 생성할 수도 있기 때문에 사용자당 최대 2개까지 인증키를 발급받을 수 있습니다.
발급된 인증키 관리와 확인, 인증키 생성은 네이버 클라우드 플랫폼 포털의 마이페이지 > 계정 관리 > 인증키 관리에서 진행할 수 있습니다.
- 네이버 클라우드 플랫폼 포털에서 계정을 생성하는 방법과 인증키를 생성하는 자세한 방법은 포털 및 콘솔 사용 가이드의 회원 가입과 보안 설정을 참고해 주십시오.
- 네이버 클라우드 플랫폼의 Sub Account를 통해 인증키를 생성하거나 관리하는 방법이 궁금한 경우 Sub Account 사용 가이드를 참고해 주십시오.
인증키를 사용 중지로 설정하거나 삭제하면 유효하지 않은 키로 인식되므로 주의해 주십시오.
2. 헤더 생성
생성한 인증키를 사용하여 헤더를 생성합니다. 헤더에는 인증과 관련된 파라미터(AUTHPARAMS)가 포함됩니다. 여기에서 설명하는 헤더는 NAVER Cloud Platform API에 속하는 API들의 공통 헤더이며, 서비스별 API의 헤더 구성은 조금씩 상이할 수 있습니다. 서비스별 API의 헤더 구성은 각 서비스 API 가이드를 참고해 주십시오.
NAVER Cloud Platform API의 공통 헤더에 대한 설명은 다음과 같습니다.
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'
시그니처 생성
시그니처는 공통 헤더 마지막 필드(x-ncp-apigw-signature-v2)에 들어가는 값입니다. 시그니처 생성 방법은 다음과 같습니다.
- 개행문자는
\n
을 사용 - 요청에 맞게 StringToSign을 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩
- 인코딩한 값을 x-ncp-apigw-signature-v2로 사용
요청 헤더의 x-ncp-apigw-timestamp 값과 StringToSign의 timestamp는 반드시 같은 값이어야 합니다.
요청 | 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)
}
3. 응답 상태 코드
1.~2.의 내용을 토대로 API를 호출합니다. API 호출에 대한 결과는 성공과 실패로 구분할 수 있습니다. 응답에 성공한 경우 리턴된 결과를 확인합니다. 응답에 실패한 경우 오류 코드가 리턴됩니다. 리턴된 오류 코드를 확인하여 호출을 다시 시도해 주십시오.
성공
요청이 성공한 경우, 반환되는 코드는 다음과 같습니다.
HTTP 상태 코드 | 메시지 | 설명 |
---|---|---|
200 | OK | 요청 성공 |
201 | Created | 요청의 결과로 새로운 리소스가 생성됨 |
202 | Accepted | 요청이 수락되었지만 아직 완료되지 않았음 |
실패
호출에 실패하여 리턴되는 오류 코드에는 서비스 공통 오류 코드와 서비스별 오류 코드가 있습니다. 서비스별 오류 코드는 각 서비스별 API 가이드의 오류 코드를 참고해 주십시오.
공통 오류 코드의 경우 JSON 형식이 기본값(default)입니다. 공통 오류 코드별 메시지와 설명은 다음과 같습니다.
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 | 예외 처리가 안된 오류 |
공통 오류 코드 예시는 다음과 같습니다.
요청 파라미터가
Content-type: application/json
인 경우{ "error":{ "errorCode":"210", "message":"Permission Denied" } }
요청 파라미터가
Content-type: application/xml
인 경우<?xml version='1.0' encoding='UTF-8' ?> <Message> <error> <errorCode>210</errorCode> <message>Permission Denied</message> </error> </Message>
API 인증 방식
NAVER Cloud Platform API의 V1 버전에서는 계정별 Key를 발급받아 인증에 활용하는 API Key 인증 방식을 사용했습니다. 그렇기 때문에 API 호출 시 API Key를 헤더에 반드시 포함해야 했습니다.
- API Key는 네이버 클라우드 플랫폼의 API Gateway를 통해 생성할 수 있습니다. 자세한 생성 방법은 API Gateway 사용 가이드를 참고해 주십시오.
- API Gateway에서 API key 발급 시 API key만 발급하는 것이므로 API Gateway에 대한 별도의 과금은 발생하지 않습니다.
하지만 2022년 1월 1일부터는 V1 버전의 서비스를 종료하고 API Key 적용이 필요 없는 V2 버전으로 제공하고 있습니다. V2 버전은 오퍼레이션 및 기본 호출 방식이 V1 버전과 동일하나, API 호출 시 API Key를 헤더에 포함시킬 필요가 없으므로 API Gateway를 신청하지 않아도 되기 때문에 이용이 간편하다는 장점이 있습니다.
하지만 일부 서비스에서는 API Key를 통한 인증 방식이 반드시 필요한 경우가 있으므로 각 서비스의 API 가이드에서 API Key의 필수 적용 여부를 확인한 후 사용해 주십시오.