Ncloud API

NAVER Cloud Platform API(Ncloud API)의 지원 정보를 확인하고 API 공통 호출 및 인증 방법을 확인합니다.

지원 API

NAVER Cloud Platform API는 네이버 클라우드 플랫폼 서비스 및 솔루션의 다양한 기능을 제어할 수 있습니다. 호환 API와 연동 API를 제외한 모든 API가 해당됩니다. 서비스별 지원하는 구체적인 API 목록은 서비스별 API 가이드에서 확인해 주십시오.

API 호출

NAVER Cloud Platform API는 RESTful API 방식으로 제공되며, XML와 JSON 형식으로 응답합니다. 액션에 따라 파라미터 값을 입력하고 등록, 수정, 삭제, 조회할 수 있으며, 서비스 및 운영 도구 자동화에 활용할 수 있습니다. HTTP 방식의 GET/POST 메서드 호출을 통해서 사용되며 잘못된 호출 시 오류 코드와 메시지를 리턴합니다. NAVER Cloud Platform API 호출 단계는 다음과 같습니다.

1. 인증키 생성
2. 헤더 생성
3. 호출

1. 인증키 생성

NAVER Cloud Platform API를 사용하려면 우선 인증키를 생성해야 합니다. 인증키는 권한을 가진 사용자만 해당 API를 호출할 수 있도록 사용자를 식별하는 도구입니다. Access Key와 Secret Key의 한 쌍으로 구성되어 있으며, Access Key와 Secret Key는 API 인증 시 전달되는 파라미터로 사용됩니다.
NAVER Cloud Platform API 인증키는 네이버 클라우드 플랫폼 계정 생성 시 자동으로 1개가 생성됩니다. 자동 생성된 인증키 외에 사용자가 포털에서 직접 생성할 수도 있기 때문에 사용자당 최대 2개까지 인증키를 발급받을 수 있습니다.
발급된 인증키 관리와 확인, 인증키 생성은 네이버 클라우드 플랫폼 포털의 마이페이지 > 계정 관리 > 인증키 관리에서 진행할 수 있습니다.

2. 헤더 생성

생성한 인증키를 사용하여 헤더를 생성합니다. 헤더에는 인증과 관련된 파라미터(AUTHPARAMS)가 포함됩니다. 여기에서 설명하는 헤더는 NAVER Cloud Platform API에 속하는 API들의 공통 헤더이며, 서비스별 API의 헤더 구성은 조금씩 상이할 수 있습니다. 서비스별 API의 헤더 구성은 각 서비스 API 가이드를 참고해 주십시오.
NAVER Cloud Platform API의 공통 헤더에 대한 설명은 다음과 같습니다.

생성한 헤더를 이용한 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.fin-ntruss.com/photos/puppy.jpg?query1=&query2'

시그니처 생성

시그니처는 공통 헤더 마지막 필드(x-ncp-apigw-signature-v2)에 들어가는 값입니다. 시그니처 생성 방법은 다음과 같습니다.

• 개행문자는 \n을 사용
• 요청에 맞게 StringToSign을 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩
• 인코딩한 값을 x-ncp-apigw-signature-v2로 사용

언어별 시그니처 요청 예시는 다음과 같습니다.

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 호출에 대한 결과는 성공과 실패로 구분할 수 있습니다. 응답에 성공한 경우 리턴된 결과를 확인합니다. 응답에 실패한 경우 오류 코드가 리턴됩니다. 리턴된 오류 코드를 확인하여 호출을 다시 시도해 주십시오.

성공

서비스 API 호출에 대한 응답 처리 방법은 각 서비스별 API 가이드의 응답 정보를 참고해 주십시오.

실패

호출에 실패하여 리턴되는 오류 코드에는 서비스 공통 오류 코드와 서비스별 오류 코드가 있습니다. 서비스별 오류 코드는 각 서비스별 API 가이드의 오류 코드를 참고해 주십시오.
공통 오류 코드의 경우 JSON 형식이 기본값(default)입니다. 공통 오류 코드별 메시지와 설명은 다음과 같습니다.

공통 오류 코드 예시는 다음과 같습니다.

• 요청 파라미터가 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를 헤더에 반드시 포함해야 했습니다.

하지만 2022년 1월 1일부터는 V1 버전의 서비스를 종료하고 API Key 적용이 필요 없는 V2 버전으로 제공하고 있습니다. V2 버전은 오퍼레이션 및 기본 호출 방식이 V1 버전과 동일하나, API 호출 시 API Key를 헤더에 포함시킬 필요가 없으므로 API Gateway를 신청하지 않아도 되기 때문에 이용이 간편하다는 장점이 있습니다.
하지만 일부 서비스에서는 API Key를 통한 인증 방식이 반드시 필요한 경우가 있으므로 각 서비스의 API 가이드에서 API Key의 필수 적용 여부를 확인한 후 사용해 주십시오.