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

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



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



概要

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

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

APIリクエスト

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

APIリクエストの構成

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

区分 説明
API URL NAVERクラウドプラットフォーム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

認証パラメータに関する詳しい内容は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
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}は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>
      

関連情報のご確認

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

に対する検索結果は~件です。 ""

    に対する検索結果がありません。 ""

    処理中...