Ncloud API
    • PDF

    Ncloud API

    • PDF

    Article Summary

    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 목록과 다운로드는 다음과 같습니다.


    지원 API 및 SDK

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

    서비스SDK
    Serverncloud_server.zip
    Load Balancerncloud_loadbalancer.zip
    Auto Scalingncloud_autoscaling.zip
    CDN+ncloud_cdn.zip
    Cloud Outbound Mailerncloud_outboundmailer.zip

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

    성공

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

    실패

    호출에 실패하여 리턴되는 오류 코드에는 서비스 공통 오류 코드와 서비스별 오류 코드가 있습니다. 서비스별 오류 코드는 각 서비스별 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>
      

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

    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.