Ncloud API
    • 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 다운로드
    Serverncloud_server.zip
    Load Balancerncloud_loadbalancer.zip
    Auto Scalingncloud_autoscaling.zip
    Monitoringncloud_monitoring.zip
    Securityncloud_security.zip
    GeoLocationncloud_geolocation.zip
    CDN+ncloud_cdn_v2.zip
    Cloud DBncloud_clouddb_v2.zip
    Cloud Outbound Mailer다운로드

    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 KeySecret Key의 한 쌍으로 구성되어 있으며, Access KeySecret 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의 공통 헤더에 대한 설명은 다음과 같습니다.

    HeaderDescription
    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 상태 코드메시지설명
    200OK요청 성공
    201Created요청의 결과로 새로운 리소스가 생성됨
    202Accepted요청이 수락되었지만 아직 완료되지 않았음

    실패

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

    HTTP 상태 코드오류 코드오류 메시지설명
    400100Bad Request Exceptionprotocol(https), endocing(UTF-8) 등 Request 오류
    401200Authentication Failed인증 실패
    401210Permission Denied권한 없음
    404300Not Found Exception권한 없음
    429400Quota ExceededQuota 초과
    429410Throttle LimitedRate 초과
    429420Rate LimitedRate 초과
    413430Request Entity Too Large요청 엔티티 크기 초과
    503500Endpoint Error엔드포인트 연결 오류
    504510Endpoint Timeout엔드포인트 연결 시간 초과
    500900Unexpected 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의 필수 적용 여부를 확인한 후 사용해 주십시오.


    이 문서가 도움이 되었습니까?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.