ポータルのショートカット NAVERクラウドプラットフォームのマニュアル

[重要] API活用ガイドドキュメントサポート終了(Deprecated)のご案内

本APIドキュメントはNAVERクラウドプラットフォームの拡張性のあるAPIの提供のためにDeprecatedされ、公式的には使われず、今後、使用停止になる予定です。(2018年12月)
新しく提供されるNcloud APIsガイドでNAVERクラウドプラットフォームのAPIの使用方法について確認してください。



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

NAVERクラウドプラットフォームモニタリングAPI reference

概要

NAVERクラウドプラットフォームはNAVERの最新のコンピューティング技術と運用ノーハウが蓄積されたクラウドサービスです。NAVERクラウドプラットフォームで提供する様々な商品群の中でソリューション商品を利用できるように提供する応用プログラムインターフェース(API)をNAVERクラウドプラットフォームAPIといいます。

NAVERクラウドプラットフォームAPIはRESTfulの形で提供され、HTTP方式のGET/POSTメソッド呼び出しによって成り立ちます。

APIリクエスト

APIリクエストメッセージは次のように構成されます。

APIリクエストの構成

API URL + アクション + アクションパラメータ + レスポンスフォーマット + AUTHPARAMS

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の構成

アクションパラメータ

基本的に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

認証パラメータに関する詳しい内容はNAVERクラウドプラットフォームの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"}]}]}}
   

レスポンスのデータタイプ

NAVERクラウドプラットフォームのすべてのレスポンスはデータタイプで構成されています。

最初のResponseのタグは<アクション名 + Response>形式で構成されています。例えば、ProductListのデータタイプの基本的な構成は次の通りです。

共通的に送る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基準で並べたエラーの情報です。

• 次の表では上の表と同じエラー情報やリターンコードを基準に並べました。

アクション

アクションとアクションパラメータの情報およびレスポンスについて記述しています。

Exampleに使われる${MONITORING_API_URL}はNAVERクラウドプラットフォームモニタリング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) | 1秒当たりの転送ビット数 - 受信(NetworkIn) | 1秒当たりの転送ビット数 - 送信 (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. 説明

   NAVERクラウドプラットフォームでは(サーバ)インスタンスの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) | 1秒当たりの転送ビット数 - 受信(NetworkIn) | 1秒当たりの転送ビット数 - 送信(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>
      

関連情報のご確認

次のガイドで関連情報を確認できます。

• OAuth利用ガイド
• モニタリングAPI開始ガイド