Ncloud API
  • PDF

Ncloud API

  • PDF

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

NAVERクラウドプラットフォームAPI(Ncloud API)のサポート情報を確認して、API共通呼び出しと認証方法を確認します。

サポートAPIとSDK

NAVERクラウドプラットフォームAPI、サーバ、Load Balancer、Auto Scaling、モニタリング、セキュリティ、GeoLocation、ハッシュフィルタ等の様々な機能を制御できます。 サポートするAPIとSDKの情報を確認します。

API

互換APIと連携APIを除く、全てのAPIが該当します。 サービス別にサポートする具体的なAPIリストは、サービス別APIガイドで確認してください。

SDK

各サービスでサポートするSDKリストとダウンロードは、以下のとおりです。

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

API呼び出し

NAVERクラウドプラットフォームのAPIは、RESTful API方式で提供され、XMLとJSON形式で返します。 アクションに応じてパラメータ値を入力して登録、修正、削除、照会でき、サービスと運営ツールの自動化にも活用できます。 HTTP方式のGET/POSTメソッド呼び出しで使用され、誤った呼び出しを行った時、エラーコードとメッセージを返します。 NAVERクラウドプラットフォームのAPIの呼び出し段階は、以下のとおりです。

1. 認証キーの作成
2. ヘッダの作成
3. 呼び出し

1. 認証キーの作成

NAVERクラウドプラットフォームのAPIを使用するには、まず認証キーを作成する必要があります。 認証キーは、権限を持つユーザーのみ該当し、APIを呼び出せるようにユーザーを識別するツールです。 Access KeySecret Keyのペアで構成されており、Access KeySecret KeyはAPIの認証時に渡されるパラメータとして使用されます。
NAVERクラウドプラットフォームのAPI認証キーは、NAVERクラウドプラットフォームのアカウントを作成する際、自動で1つ作成されます。 自動作成された認証キーに加えて、ユーザーがポータルから直接作成することもできるため、ユーザーごとに最大2つの認証キーを発行できます。
発行された認証キーの管理と確認、認証キーの作成は、NAVERクラウドプラットフォームのポータルのマイページ > アカウントの管理 > 認証キーの管理で行えます。

参考
  • NAVERクラウドプラットフォームのポータルでアカウントを作成する方法と、認証キーを作成する方法の詳細については、ポータルとコンソールご利用ガイドの会員登録セキュリティ設定を参考にしてください。
  • NAVERクラウドプラットフォームのSub Accountで、認証キーを作成したり、管理する方法については、Sub Accountのご利用ガイドを参考にしてください。
注意

認証キーを「使用停止」に設定したか、削除した場合、有効ではないキーとして認識されるのでご注意ください。

2. ヘッダの作成

作成した認証キーを使って、ヘッダを作成します。 ヘッダには、認証に関するパラメータ(AUTHPARAMS)が含まれています。 ここで説明するヘッダは、NAVERクラウドプラットフォームのAPIに属するAPIの共通ヘッダですので、サービス別のAPIのヘッダ構成とは若干異なる場合があります。 各サービスのAPIのヘッダ構成は、サービス別のAPIガイドを参考にしてください。
NAVERクラウドプラットフォームのAPI共通ヘッダに関する説明は、以下のとおりです。

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'

シグネチャーの作成

シグネチャーは、共通ヘッダの最後のフィールド(x-ncp-apigw-signature-v2)に入る値です。 シグネチャーの作成方法は以下のとおりです。

  • 改行文字は\nを使用
  • リクエストに合わせてStringToSignを作成し、SecretKeyをHmacSHA256アルゴリズムで暗号化した後、Base64でエンコード
  • エンコードした値をx-ncp-apigw-signature-v2で使用
注意

リクエストヘッダのx-ncp-apigw-timestampの値と、StringToSignのtimestampは必ず同じ値でなければなりません。

リクエスト 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)
}

3. 呼び出し

  1. ~2.の内容をもとにAPIを呼び出します。 APIの呼び出しに対する結果は成功か失敗で区分できます。 リスポンスが成功した場合、返された結果を確認します。 リスポンスに失敗した場合、エラーコードが返されます。 返されたエラーコードを確認して、呼び出しを再試行してください。

成功

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

失敗

呼び出しに失敗して返されるエラーコードには、サービス共通のエラーコードとサービス別のエラーコードがあります。 サービス別のエラーコードについては、各サービスのAPIガイドのエラーコードを参照してください。
共通のエラーコードの場合、JSON形式はデフォルト値(default)です。 共通のエラーコード別メッセージと説明は、以下のとおりです。

HTTPステータスコード エラーコード エラーメッセージ 説明
400 100 Bad Request Exception プロトコル(HTTPS)、エンコード(UTF-8)などのリクエストエラー
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 例外処理していないエラー

共通のエラーコードの例は、以下のとおりです。

  • リクエストパラメータが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認証方式

NAVERクラウドプラットフォームのAPIのV1バージョンでは、アカウント別のKeyを発行して認証に活用するAPI Key認証方式を使用していました。 そのため、APIを呼び出す際、API Keyをヘッダに必ず含まなければなりませんでした。

参考
  • API Keyは、NAVERクラウドプラットフォームのAPI Gatewayを用いて作成することができます。 詳しい作成方法は、API Gatewayご利用ガイドを参考にしてください。
  • API GatewayでAPI keyを発行する際、API keyのみ発行されるため、API Gatewayに対する別途の課金は発生しません。

しかし、2022年1月1日からはV1バージョンのサービスを終了し、API Keyの適用が不要なV2バージョンで提供しています。 V2バージョンは、オペレーションおよび基本呼び出し方式がV1バージョンと同じですが、APIを呼び出す際にAPI Keyをヘッダに含める必要がないため、API Gatewayを申し込まなくてもよいので、利用が簡単であるという利点があります。
ただし、一部のサービスでは、API Keyによる認証方式が必ず必要な場合がありますので、各サービスのAPIガイドでAPI Keyの必須適用有無を確認した上でご使用ください。


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

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.