NAVERクラウドプラットフォームAPI
  • PDF

NAVERクラウドプラットフォームAPI

  • PDF

概要

NAVERクラウドプラットフォームが提供するサービスとソリューションを活用できるようにサポートするアプリケーションインターフェース(API)を、NAVERクラウドプラットフォームAPIといいます。

本ページではNaverクラウドプラットフォームAPIに対する簡略な説明及びAPIを呼び出す方法を提供します。

APIはRESTful API方式で提供されるし、XMLとJSON形式でレスポンスします。アクションによってパラメータ値を入力して、登録、修正、削除、照会できますし、サービス及び運営ツール自動化に活用できます。HTTP方式のGET/POSTメソッド呼び出しを通じて使用できます。
もし、呼び出しが間違った場合には、エラーコードとメッセージをリターンします。

NaverクラウドプラットフォームAPIの呼び出し手順

NaverクラウドプラットフォームAPIの呼び出しは以下のような段階で進める必要があります。
1. 認証キーの作成
2. APIの呼び出し
3. レスポンスの処理
4. エラーの処理

認証キーの作成

Naverクラウドプラットフォームのアカウントが作成される場合、基本的にNaverクラウドプラットフォームのAPI認証キーが一つ発行されます。発行された認証キーは Naverクラウドプラットフォームホームページマイページ > アカウント管理 > 認証キー管理 で確認できます。認証キーはアカウントを作成する時、自動で発行されるもの以外に、ユーザーがもう一つ作成できるので2個まで発行できます。

参考

認証キーを '使用中止'に設定するか削除すると有効でないキーとして認識されます。

API認証キーは Access KeySecret Key のペアで構成されています。ペアのAPI認証キーはAPIを認証する時にパラメータで直接伝達されます。

  1. Naverクラウドプラットフォームのホームページにログインします。
  2. マイページ > アカウント管理 > 認証キー管理 メニューにアクセスして"新規API認証キー作成" ボタンをクリックします。
    • 既存作成した認証キーがある場合には、該当認証キーが使えます。
  3. API認証キー管理で発行された自分の Access Key IDSecret Keyを確認します。

APIの呼び出し

AUTHPARAMS

Header Description
x-ncp-apigw-timestamp * 1970年1月1日 00:00:00 協定世界時(UTC)からの経過時間をミリセカンド(Millisecond)で表したものです。
* API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとしてみなす。
x-ncp-iam-access-key * Naverクラウドプラットフォームポータルまたは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.ntruss.com/photos/puppy.jpg?query1=&query2'
  • Signatureの作成
    • 改行文字は \nを使います。
    • リクエストに合わせてStringToSignを作成し、SecretKeyでHmacSHA256アルゴリズムに暗号化してから、Base64でエンコーディングします。
    • この値をx-ncp-apigw-signature-v2に使います。
リクエスト 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)
}

レスポンスの処理

  • サービスAPIの呼び出しに対するレスポンスは、各サービスのAPIガイドを参考にしてください。

エラーの処理

  • サービスAPIの呼び出しに対するエラーコードは、各サービスのAPIガイドを参考にしてください。

共通エラーコード

  • リクエストパラメータが Content-type: application/jsonの場合(default)
{
   "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>
HTTPステータスコード エラーコード エラーメッセージ 説明
400 100 Bad Request Exception protocol(https), endocing(UTF-8)など Requestエラー
401 200 Authentication Failed 認証失敗
401 210 Permission Denied 権限なし
404 300 Not Found Exception 権限なし
429 400 Quota Exceeded Quota超過
429 410 Throttle Limited Rate超過
429 420 Rate Limited Rate超過
413 430 Request Entity Too Large リクエストエンティティサイズ超過
503 500 Endpoint Error エンドポイント連結エラー
504 510 Endpoint Timeout エンドポイント連結時間超過
500 900 Unexpected Error 例外処理がされてないエラー

サポートAPI及びSDK

本NaverクラウドプラットフォームAPIは、Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation, Hash Filterなどの多様な機能をAPIで制御できます。APIはRESTful API方式で提供されるし、XML, JSON形式でレスポンスします。アクションによってパラメータ値を入力し、登録、修正、削除、照会できますし、サービス及び運営ツールの自動化に活用できます。

サービス API SDK
Server Server API ncloud_server.zip
Load Balancer Load Balancer API ncloud_loadbalancer.zip
Auto Scaling Auto Scaling API ncloud_autoscaling.zip
Monitoring Monitoring API ncloud_monitoring.zip
Security Security API ncloud_security.zip
GeoLocation GeoLocation API ncloud_geolocation.zip
CDN+ CDN+ API ncloud_cdn_v2.zip
Cloud DB Cloud DB API ncloud_clouddb_v2.zip
Cloud Outbound Mailer Cloud Outbound Mailer API ncloud_outboundmailer.zip

Ncloud APIリリースノート

NaverクラウドプラットフォームのNcloud APIsはサービスリリース以降にも多様な改善作業を通じて提供されています。

Ncloud APIs提供バージョン案内

Naverクラウドプラットフォームでは、現在3つのバージョンのサービスを提供しています。: Ncloud APIs Old, Ncloud APIs V1, Ncloud APIs V2 使用性が向上されたNcloud APIs V2バージョンの呼び出しをお勧めしますし、Ncloud APIs OldとNcloud APIs V1バージョンは案内期間をおいてから使用が中止される予定です。

  • Ncloud APIs Old
    : Naverクラウドプラットフォームの初期に提供した https://api.ncloud.com/ DomainではじまるAPIです。Ncloud APIs OldバージョンはOAuth認証方式を使います。

  • Ncloud APIs V1
    : API管理機能が向上された新しいAPI Gatewayを通じて https://ncloud.apigw.ntruss.com/ DomainではじまるAPIです。Ncloud APIs V1バージョンからはAPI Gatewayで発行したAPI Keyを通じた認証方式を提供します。

    : Ncloud APIs V1を呼び出す時には、API Gatewayで発行したAPI keyが必要であるため、API Gatewayサービスの申し込みが必要です。(但し、API keyのみが発行されるため、API Gatewayに対する課金は発生しません。)

  • Ncloud APIs V2
    : Ncloud APIs V2はAPI keyが必要ない方式であり、オペレーション及び呼び出し方式はNcloud APIs V1と同じです。しかし、API Gatewayの申し込みが必要ないため、便利です。

    :サービス別にAPI Keyを必須で適用する必要がある場合があるので、API Keyの使用に関しては各サービスのサポートAPI明細によります。

Ncloud API認証方式

  1. OAuth認証方式

    • Ncloud APIs Oldバージョンで使う方式であり、別途のシステムが該当ログイン情報を保存せずに暗号化された認証トークンを使う場合のみ、リソースへのアクセスができます。
  2. API Key認証方式

    • API Key認証方式はアカウント別のKeyを発行して認証に活用する方式です。API KeyはNaverクラウドプラットフォームコンソールの API Gateway > API Key で "API Key作成" メニューを通じて API Keyを作成できます。

    • Ncloud APIs V1の場合は、呼び出す時、API Keyをヘッダに必ず含む必要があります。

    • Ncloud APIs V2の場合は、呼び出す時、API Keyをヘッダに必ず含む必要がありません。

以前バージョンガイドへのショットカット

サービス Ncloud APIs V1 : (API Key認証) Ncloud APIs V2 : (API Key認証なし)
Server ガイドの表示 Server API
Load Balancer ガイドの表示 Load Balancer API
Auto Scaling ガイドの表示 Auto Scaling API
Monitoring ガイドの表示 Monitoring API
Security ガイドの表示 Security API
GeoLocation ガイドの表示 GeoLocation API
CDN ガイドの表示 CDN API
Global CDN ガイドの表示 Global CDN API
Cloud DB ガイドの表示 Cloud DB API
Cloud Outbound Mailer ガイドの表示 Cloud Outbound Mailer API

(サービス別にAPI Keyを必須で適用する場合があるので、API Keyの使用については各サービスのサポートAPIで確認してください。)

Ncloud APIs Fade out主要日程

  • Ncloud APIs V1は、2019年12月31日にサービスが終了されるため、2020年1月1日以降はサービス利用が不可能です。
  • Ncloud APIs OLDは、2019年6月30日にサービスが終了されるため、2019年6月30日以降はサービス利用が不可能です。

この記事は役に立ちましたか