[중요] API 활용 가이드 문서 지원 종료 (Deprecated) 안내

본 API 문서는 네이버 클라우드 플랫폼의 확장성 있는 API 제공을 위해 Deprecated 되어 공식적으로 사용하지 않으며, 앞으로 사용이 정지될 예정입니다. (2018년 12월)
새롭게 제공되는 Ncloud APIs 가이드에서 네이버 클라우드 플랫폼의 API 사용 방법을 확인해 주십시오.



=========================================== @deprecated 문서(~2018년12월) ==========================================



네이버 클라우드 플랫폼 모니터링 API reference

개요

네이버 클라우드 플랫폼은 NAVER의 최신 컴퓨팅 기술과 운영 노하우가 축적된 클라우드 서비스입니다. 네이버 클라우드 플랫폼에서 제공하는 여러 가지 상품군 중에 솔루션 상품을 이용할 수 있도록 제공하는 응용 프로그램 인터페이스(API)를 네이버 클라우드 플랫폼 API라고 합니다.

네이버 클라우드 API는 RESTful 형태로 제공되며, HTTP 방식의 GET/POST 메서드 호출을 통해서 이루어집니다.

API 요청

API 요청 메시지는 아래와 같이 구성됩니다.

API 요청 구성

API URL + 액션 + 액션 파라미터 + 응답 포맷 + AUTHPARAMS

구분 설명
API URL 네이버 클라우드 플랫폼 Server API URL
https://api.ncloud.com/server/?
https://api.ncloud.com/loadbalancer/?
https://api.ncloud.com/autoscaling/?
https://api.ncloud.com/monitoring/?
액션 컴퓨팅 자원 요청 액션 (생성, 삭제, 조회…)
action=createServerInstances
액션 파라미터 액션 관련 파라미터
serverName=myserver&serverImageProductCode=SPSWLINUX000031
응답 포맷 xml, json 응답 포맷을 지원하며 옵션항목입니다. default는 xml
responseFormatType=xml
AUTHPARAMS oauth_consumer_key=CCe2T0ilv4aO3kIevT3x
oauth_signature_method=HMAC-SHA1
oauth_version=1.0
oauth_timestamp=1392264315
oauth_nonce=9196882534520920143
oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%3D

API 요청 Sample

https://api.ncloud.com/server/?action=createServerInstances&serverImageProductCode=SPSW0LINUX000031&responseFormatType=xml&oauth_consumer_key=CCe2T0ilv4aO3kIevT3x&oauth_nonce=9196882534520920143&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1392264315&oauth_version=1.0&oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%3D

API 요청 Sample 구성

구분 설명
https://api.ncloud.com/monitoring/? API URL
action=createServerInstances 액션
&serverImageProductCode=SPSW0LINUX000031 액션파라미터
&responseFormatType=xml 응답포맷
&oauth_consumer_key=CCe2T0ilv4aO3kIevT3x AUTHPARAMS
&oauth_nonce=9196882534520920143 AUTHPARAMS
&oauth_signature_method=HMAC-SHA1 AUTHPARAMS
&oauth_timestamp=1392264315 AUTHPARAMS
&oauth_version=1.0 AUTHPARAMS
&oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%3D AUTHPARAMS

액션 파라미터

기본적으로 Key, Value 쌍으로 구성되어 있습니다. 리스트(List<Object>) 형식의 파라미터는 리스트형파라미터명.N 형식으로 구성되어 있고, 맵 리스트(Map <String, List<Object>>) 형식의 파라미터는 리스트명.N.파라미터명 형식으로 구성되어 있습니다. N 값은 1부터 시작되며 100을 넘길 수 없습니다.

  1. 일반적인 액션 파라미터

     &pageNo=1
     &serverName=myServer
     …
    
  2. 리스트형 액션 파라미터

     &serverInstanceNoList.1=1
     &serverInstanceNoList.2=2
     …
    
  3. Map리스트형 액션 파라미터

     &loadBalancerRuleList.1.protocolTypeCode=HTTP
     &loadBalancerRuleList.1.loadBalancerPort=80
     &loadBalancerRuleList.1.serverPort=80
     &loadBalancerRuleList.2.l7HealthCheckPath=/l7check.html
     &loadBalancerRuleList.1.protocolTypeCode=HTTP
     &loadBalancerRuleList.1.loadBalancerPort=81
     &loadBalancerRuleList.1.serverPort=81
     &loadBalancerRuleList.2.l7HealthCheckPath=/l7check2.html
     …
    

AUTHPARAMS

인증 파라미터에 대한 자세한 내용은 네이버 클라우드 플랫폼 OAuth 이용 가이드를 참고합니다. 이 가이드에서는 간략한 인증 방법에 대해서 설명합니다.

인증키를 생성하기 위해서 아래와 같은 절차를 따릅니다.

base string 생성
  1. 액션 파라미터에 base string 생성에 필요한 인증 파라미터를 추가
  2. 요청 파라미터와 value 값을 알파벳순으로 정렬
  3. base string = RequestMethod + '&' + oauthEncode(requestUrl) + '&' + oauthEncode(queryString)
  • Java 생성 예

    private SortedMap<String, SortedSet<String>> getSignificateParametersForSiganturBaseString(Map<String, List<String>> requestParameters, String consumerKey) {
          SortedMap<String, SortedSet<String>> significateParameters = convertTypeToSortedMap(requestParameters);
    
          SortedSet<String> consumerKeySet = new TreeSet<String>();
          consumerKeySet.add(consumerKey);
          significateParameters.put("oauth_consumer_key", consumerKeySet);
    
          SortedSet<String> nonceSet = new TreeSet<String>();
          nonceSet.add(generateNonce());
          significateParameters.put("oauth_nonce", nonceSet);
    
          SortedSet<String> signatureMethodSet = new TreeSet<String>();
          signatureMethodSet.add("HMAC-SHA1");
          significateParameters.put("oauth_signature_method", signatureMethodSet);
    
          SortedSet<String> timestampSet = new TreeSet<String>();
          timestampSet.add(generateTimestamp());
          significateParameters.put("oauth_timestamp", timestampSet);
    
          SortedSet<String> versionSet = new TreeSet<String>();
          versionSet.add("1.0");
          significateParameters.put("oauth_version", versionSet);
    
          return significateParameters;
      }
    
      private String makeSignatureBaseString(String requestMethod, String requestUrl, SortedMap<String, SortedSet<String>> significantParameters) {
          StringBuilder queryString = getRequestQueryString(significantParameters);
    
          requestUrl = normalizeUrl(requestUrl);
          requestUrl = OAuthCodec.oauthEncode(requestUrl);
    
          return new StringBuilder(requestMethod.toUpperCase()).append('&').append(requestUrl).append('&').append(OAuthCodec.oauthEncode(queryString.toString())).toString();
      }
    
  • Sample

    POST&http%3A%2F%2F10.101.54.72%2Fserver%2F&action%3DgetServerProductList%26oauth_consumer_key%3DCCe2T0ilv4aO3kIevT3x%26oauth_nonce%3D7179137053311691172%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1392277044%26oauth_version%3D1.0%26responseFormatType%3Dxml
    
서명서 생성

Secret Key와 위에서 생성한 baseString을 가지고 HMAC SHA-1 해시알고리즘을 이용하여 서명서를 생성합니다.

  • Java 생성 예

      private String sign(String signatureBaseString, String consumerSecret) throws NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeyException {
      Mac mac = Mac.getInstance("HmacSHA1");
      SecretKeySpec spec = new SecretKeySpec(new String(consumerSecret + "&").getBytes("UTF-8"), "HmacSHA1");
      mac.init(spec);
      byte text[] = signatureBaseString.getBytes("UTF-8");
      byte signatureBytes[] = mac.doFinal(text);
      signatureBytes = Base64.encodeBase64(signatureBytes);
      String signature = new String(signatureBytes, "UTF-8");
      logger.debug("signature : " + signature);
      return signature;
      }
    
  • Sample

    vMissQDb84MhEn7NGh1+Yuyfank=
    

API 응답

API 응답에 대해 설명합니다.

API 응답 포맷

기본적으로 xml, json 형식의 응답 포맷을 지원합니다.

  1. xml 응답

    <getZoneListResponse>
    <requestId>c385247e-6c76-4b20-ba67-509d5dc95f68</requestId>
    <returnCode>0</returnCode>
    <returnMessage>success</returnMessage>
    <zoneList>
    <zone>
    <zoneNo>2</zoneNo>
    <zoneName>zone2</zoneName>
    <zoneDescription>nang zone</zoneDescription>
    </zone>
    <zone>
    <zoneNo>3</zoneNo>
    <zoneName>zone3</zoneName>
    <zoneDescription>nang zone2</zoneDescription>
    </zone>
    </zoneList>
    </getZoneListResponse>
    
  2. json 응답

    {"getZoneListResponse":{"requestId":"b6b9d54f-2770-40bb-a8a9-cc6aa46f75e0","returnCode":0,"returnMessage":"success","zoneList":[{"zone":[{"zoneNo":2,"zoneName":"zone2","zoneDescription":"nang zone"},{"zoneNo":3,"zoneName":"zone3","zoneDescription":"nang zone2"}]}]}}
    

응답 데이터 타입

네이버 클라우드 플랫폼의 모든 응답은 데이터 타입으로 구성되어 있습니다.

첫 Response 태그는 <액션명 + Response> 형식으로 구성되어 있습니다. 예를 들면 ProductList 데이터 타입에 대한 기본적인 구성은 아래와 같습니다.

CommonResponse
private String requestId;
private String returnCode;
private String returnMessage;
ProductList extends CommonResponse
private List<Product> productList = new ArrayList<Product>();
Product
private String productCode;
private String productName;
private CommonCode productType;
private String productDescription;
private CommonCode infraResourceType;
private Integer cpuCount;
private Long memorySize;
private Long baseBlockStorageSize;
private CommonCode platformType;
private String osInformation;
private CommonCode diskType;
private Long addBlockStroageSize;

공통으로 전달하는 CommonResponse 데이터 타입이 ProductList에 extends되어 있고, ProductList는 List<Product>으로 구성되어 있습니다.

오류 처리

API 요청이 잘못되거나 처리 도중 오류가 발생하면 오류 정보를 응답으로 전달합니다.
오류 발생 시 HTTP Response Code는 200 OK 외의 값이 전달됩니다. 오류 정보는 리턴코드 <returnCode>와 리턴메시지 <returnMessage>로 구성되며, CommonResponse 데이터 타입을 가집니다. 또한 모든 오류는 <responseError>라는 이름으로 리턴됩니다.

  • 사용자 오류 예: HTTP Response Code = 400

      <responseError>
      <returnCode>900</returnCode>
      <returnMessage>
      Required field is not specified. location : serverImageProductCode.
      </returnMessage>
      </responseError>
    
  • Sample – 인증오류 : HTTP Response Code = 401

      <responseError>
      <returnCode>801</returnCode>
      <returnMessage>Signature is invalided</returnMessage>
      </responseError>
    
  • 아래는 HTTP Response Code 기준으로 정렬한 오류 정보입니다.

HTTP Response Code 리턴코드 리턴메시지
400 900 – 999 파라미터 관련 오류
400 1100 BAD REQUEST
400 1400 – 1499 사용자에 의해 발생한 기타 오류
400 10000 – 29999 사용자에 의해 발생한 기타 오류
401 800 – 899 인증관련 오류
404 1101 NOT FOUND
405 1102 METHOD NOT ALLOWED
500 1000 - 1399 서버 내부 오류
  • 아래 표는 위의 표와 동일한 오류 정보이나 리턴 코드 기준으로 정렬했습니다.
HTTP Response Code 리턴코드 리턴메시지
401 800 – 899 인증관련 오류
400 900 – 999 파라미터 관련 오류
500 1000 - 1399 서버 내부 오류
400 1100 BAD REQUEST
404 1101 NOT FOUND
405 1102 METHOD NOT ALLOWED
400 1400 – 1499 사용자에 의해 발생한 기타 오류
400 10000 – 29999 사용자에 의해 발생한 기타 오류

액션

액션과 액션 파라미터 정보 및 응답에 대해서 기술하였습니다.

Example에 사용되는 ${MONITORING_API_URL}은 네이버 클라우드 플랫폼 모니터링 API URL(https://api.ncloud.com/monitoring/?)입니다.

Monitoring

getListMetrics

  1. API명

    Metric 리스트 조회

  2. 설명

    통계 정보를 제공 받을 수 있는 항목(Metric)이 어떤 것들이 있는지 조회할 수 있는 API를 제공합니다.

  3. 요청 파라미터

    파라미터명 간략 설명 타입 제약 필수여부
    instanceNo (서버)인스턴스번호 String Yes
    metricName 통계 항목(Metric) 이름 String No
    1. instanceNo: 조회할 대상이 되는 (서버)인스턴스 번호를 입력합니다.
    2. metricName: 특정 항목(Metric)이 통계 정보로 제공 가능한지 확인할 때 입력합니다. 아래의 값이 입력될 수 있습니다.

       CPU사용률(CPUUtilization) | 디스크의 데이터를 저장하는 용량(DiskWriteBytes) | 디스크의 데이터를 읽어들이는 용량(DiskReadBytes) | 초당 전송 비트수 - 수신(NetworkIn) | 초당 전송 비트수 - 송신 (NetworkOut)
      
  4. 응답 데이터 타입

    • listMetrics

      ListMetrics extends CommonResponse
      private List<Metric> metrics = new ArrayList<Metric>();
      Metric
      private String instanceNo;
      private String metricName;
  5. 오류

  6. Example

    1. 요청

       ${SERVER_API_URL}?action=getListMetric
       &instanceNo=68417
       &AUTHPARAMS
      
    2. 응답

       <getListMetricsResponse>
       <requestId>77122dd7-e61f-4f43-ba0b-f17a1b52b760</requestId>
       <returnCode>0</returnCode>
       <returnMessage>success</returnMessage>
       <metrics>
       <member>
       <instanceNo>68417</instanceNo>
       <metricName>CPUUtilization</metricName>
       </member>
       <member>
       <instanceNo>68417</instanceNo>
       <metricName>DiskReadBytes</metricName>
       </member>
       <member>
       <instanceNo>68417</instanceNo>
       <metricName>DiskWriteBytes</metricName>
       </member>
       <member>
       <instanceNo>68417</instanceNo>
       <metricName>NetworkIn</metricName>
       </member>
       <member>
       <instanceNo>68417</instanceNo>
       <metricName>NetworkOut</metricName>
       </member>
       </metrics>
       </getListMetricsResponse>
      

getMetricStatistics

  1. API명

    Metric별 통계 정보 조회

  2. 설명

    네이버 클라우드 플랫폼에서는 (서버)인스턴스들의 Metric에 대한 통계 정보를 일정 주기마다 수집하고 있으며, 사용자가 이를 활용할 수 있도록 조회 API를 제공합니다.

  3. 요청 파라미터

    파라미터명 간략 설명 타입 제약 필수여부
    instanceNoList (서버)인스턴스 번호 String Min:1, Max:30 Yes
    metricName 통계 항목(Metric) 이름 String Yes
    startTime 조회 시작일시 Date Yes
    endTime 조회 종료일시 Date Yes
    period 조회주기 (초) String Yes
    1. instanceNo: 통계 정보를 조회할 (서버)인스턴스 번호 리스트를 입력합니다.
    2. metricName: 통계 정보를 조회하려고 하는 항목(Metric)의 이름을 입력합니다. 아래의 값이 입력될 수 있습니다.

       CPU사용률(CPUUtilization) | 디스크의 데이터를 저장하는 용량(DiskWriteBytes) | 디스크의 데이터를 읽어들이는 용량(DiskReadBytes) | 초당 전송 비트수 - 수신(NetworkIn) | 초당 전송 비트수 - 송신 (NetworkOut)
      
    3. startTime: 통계 데이터의 최초 조회 시점을 다음과 같은 형식으로 입력합니다.

       형식: yyyy-MM-dd'T'HH:mm:ssZ
       예제: 2013-07-25T17:50:00+0900, 2013-07-25T08:50:00Z
      
    4. endTime: 통계 데이터의 마지막 조회 시점을 다음과 같은 형식으로 입력합니다.

       형식: yyyy-MM-dd'T'HH:mm:ssZ
       예제: 2013-07-25T17:50:00+0900, 2013-07-25T08:50:00Z
      
    5. period: 통계 데이터를 추출하기 위한 기초 데이터의 수집 기간을 입력합니다. 아래와 같은 수집 기간을 입력할 수 있습니다.

      수집기간 데이터 보관주기
      1분 8일
      5분 40일
      30분 6개월
      2시간 2년
      1일 5년
  4. 응답 데이터 타입

    • MetricStatistics

      MetricStatistics extends CommonResponse
      private List<Statistics> statistics = new ArrayList<Statistics>();
      Statistic
      private String instanceNo;
      private List<DataPoints> dataPointsList = new ArrayList<DataPoints>();
      DataPoints
      private String label;
      private Double average;
      private Double maximum;
      private Double minimum;
      private Double sum;
      private List<DataPoint> dataPointList = new ArrayList<DataPoint>();
      DataPoint
      private String timestamp;
      private Double average;
      private String unit;
  5. 오류

    HTTP Response Code 리턴코드 리턴메시지
    400 41101 At most 1800 data items can be gotten at once. Verify interface parameters.
    400 41102 period of data acquisition which can be set are 1 min, 5 min, 30 min, 2 hours, and 1 day
    400 41103 Start time must be earlier than end time.
    400 41104 Statistics data of each period is stored for the following terms. 1min, stored up to 8days. 5min, stored up to 40days. 30min, stored up to 6months. 2hour, stored up to 2years. 1day, stored up to 5years.
  6. Example

    1. 요청

       ${SERVER_API_URL}?action=getMetricStatistics
       &instanceNoList.1=68417&metircName=CPUUtilization&startTime=2014-06-10T17:50:00+0900&endTime=2014-06-10T18:50:00+0900&period=1800
       &AUTHPARAMS
      
    2. 응답

       <getMetricStatisticsResponse>
       <requestId>d3ea7fbd-9bff-4ff0-a2ef-78817575943e</requestId>
       <returnCode>0</returnCode>
       <returnMessage>success</returnMessage>
       <statistics>
       <statistic>
       <instanceNo>68417</instanceNo>
       <dataPoints>
       <label>CPUUtilization</label>
       <average>0.08812500000000001</average>
       <maximum>0.090833</maximum>
       <minimum>0.085417</minimum>
       <sum>0.17625000000000002</sum>
       <member>
       <timestamp>2014-06-10T09:00:00Z</timestamp>
       <average>0.090833</average>
       <unit>Percent</unit>
       </member>
       <member>
       <timestamp>2014-06-10T09:30:00Z</timestamp>
       <average>0.085417</average>
       <unit>Percent</unit>
       </member>
       </dataPoints>
       </statistic>
       </statistics>
       </getMetricStatisticsResponse>
      

연관 정보 바로가기

다음 가이드에서 연관 정보를 확인할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...