Ncloud API

Classic/VPC環境で利用できます。

NAVERクラウドプラットフォームの APIは RESTful APIとして提供され、JSONと XML形式で返します。アクションに応じてパラメータ値を入力して登録、変更、削除、照会でき、サービスと運営ツールの自動化にも活用できます。HTTPでメソッドを呼び出し、呼び出しに失敗するとエラーコードとメッセージを返します。Ncloud APIには、互換 APIと連携 APIを除く、NAVERクラウドプラットフォームのすべての APIが該当します。

API認証キー

NAVERクラウドプラットフォーム APIは、権限を持つユーザーのみ呼び出すことができるようにユーザー識別ツールである API認証キーをAccess keyとSecret keyのワンセットで構成して、アカウント別に発行しています。これは API呼び出しの認証時に渡されるパラメータとして使用します。そのため、NAVERクラウドプラットフォームの APIを使用するには、まず認証キーを作成する必要があります。
認証キーの作成と管理は NAVERクラウドプラットフォームのポータルで行います。NAVERクラウドプラットフォームポータルで認証キーを作成・管理する方法は、次の通りです。

1. NAVERクラウドプラットフォームポータルにログインします。
2. マイページ > アカウント管理 > 認証キー管理メニューを順にクリックします。
3. API認証キーの管理でデフォルトで提供される Access key IDと Secret keyを確認します。
4. 必要な作業を行います。
   • API認証キーの追加発行
     • [新規 API認証キーを作成] ボタンをクリック
   • API認証キーの使用停止
     • [使用停止] ボタンをクリック
     • 使用停止した認証キーを再び使用するには、 [使用] ボタンをクリック
   • API認証キーの削除
     • [削除] ボタンをクリック
     • 使用停止した認証キーのみ削除可能

APIの共通設定

Ncloud APIで共通して使用されるリクエスト形式とレスポンス形式を説明します。

リクエスト

共通リクエスト形式を説明します。

API URL

リクエスト API URLは、サービス別 APIガイドで確認してください。

シグネチャーの作成

シグネチャーは、共通リクエストヘッダのx-ncp-apigw-signature-v2フィールドに入る値で、リクエスト情報を API認証キー(AccessKeyとマッピングするSecretKey)で暗号化した後、Base64でエンコードして作成する署名です。暗号化には、HMAC暗号化アルゴリズム(HmacSHA256)が使用されます。
シグネチャーを作成する言語別サンプルコードは次の通りです。

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
*/



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)
}

リクエストヘッダ

NAVERクラウドプラットフォーム APIの共通ヘッダは、認証関連のフィールドを含みます。リクエストヘッダの説明は次の通りです。

リクエスト例

認証キーと共通ヘッダを使用したリクエストのサンプルコードは次の通りです。

curl --location --request GET 'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \

レスポンス

共通レスポンス形式を説明します。

レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

レスポンス例

レスポンスのサンプルコードは次の通りです。

• 成功(Content-type: application/json)

  {
    "status": {
      "code": "20000",
      "message": "OK"
    },
    "result": {...}
  }
  

• 成功(Content-type: application/xml)

  <Message>
     <status>
         <code>20000</code>
         <message>OK</message>
     </status>
     <result> ... </result>
  </Message>
  

• 失敗(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のセキュリティ設定

API認証キーが第三者に流出する場合、リソースを任意に変更したり照会することができるため、セキュリティ上の深刻な問題が発生する可能性があるので、適切な事前準備と対応が必要です。

API認証キーの再発行

API認証キーを使用していないか、盗用が疑われる場合は、発行した認証キーを使用停止するか、削除した後、再発行してください。

サブアカウント認証キーの使用

すべての権限を持つメインアカウントでないサブアカウントで API認証キーを発行して APIを呼び出し、認証キーの流出に備えて定期的に交換することもできます。サブアカウントはロールに合った権限だけ付与され使用することができます。さらに、IPアドレス帯域だけでなく、VPCまで API Access Sourceの指定が可能なため、セキュリティ上より安全に APIを使用できます。
サブアカウントは、NAVERクラウドプラットフォームの Sub Accountサービスで作成します。サブアカウントと API認証キーの作成方法は、Sub Accountご利用ガイドをご参照ください。

APIアクセス制限の設定

許可されていない位置からの API Gatewayアクセスをブロックするために、特定の IPアドレス帯域からのみ使用できるように設定できます。特定の IPアドレス帯域でのみ APIを使用できるように設定する方法は、次の通りです。

1. NAVERクラウドプラットフォームポータルにログインします。
2. マイページ > アカウント管理 > 認証キー管理メニューを順にクリックします。
3. APIアクセス制限の設定の IP Addressにアクセスを許可する IPアドレス帯域を入力します。
   • CIDR表記を参照して入力してください。
   • 0.0.0.0~32帯域はセキュリティ上、入力できません。
   • 別途登録しない場合、すべてのアクセスを許可します。
4. [保存] ボタンをクリックします。
   • アクセス許可 IPアドレス帯域を追加するには、 [追加] ボタンをクリックします。

CIDR表記

IP Addressは、192.168.0.1 ~ 192.168.0.255形式でアクセスを許可する IPアドレス帯域を表記します。NAVERクラウドプラットフォームは、ネットワークを管理する際に主に使用される CIDR(Classless Inter-Domain Routing)表記を使用して入力する方法もサポートします。

CIDRは、連続した IPアドレス範囲を表記する方法の1つです。CIDR表記は、IPアドレスを Net ID(Network ID)と Host IDに区分し、Net IDの下位に属する IPアドレス帯域(Host IDカテゴリ)をグループ化して表現することができます。これを Address Aggregation/Supernettingともいいます。

一般に使用する IPアドレスは次のように4オクテット(Octet)で構成されています。

CIDR表記は、IPアドレス帯域を4Octetで構成された IPアドレスとスラッシュ「/」の後ろに Rangeを1つ加えて表記します。Rangeは0~32、すなわち32ビットまで使用できます。CIDR表記では、表記された Rangeの後ろに来ることができるビットを使用できるという意味で理解できます。
そのため、IPアドレス帯域は、IPアドレスで表記された4Octetから Rangeの後ろに来ることができるビットまでの範囲を IPアドレス帯域として計算します。この時、IPアドレスの4Octet ~ Rangeまでのビットを固定領域である Net IDとみなし、残りのビットを使用できる Host ID帯域として計算します。

各 Rangeに対応する Hostの IPアドレス数は次の通りです。

サポート APIと SDK

NAVERクラウドプラットフォームがサポートする APIと SDK情報をご案内します。

API

各サービスがサポートする APIリストは、サービス別 APIガイドで確認してください。

SDK

各サービスがサポートする SDKリストとダウンロードリンクは、次の通りです。