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のダウンロード
    Serverncloud_server.zip
    Load Balancerncloud_loadbalancer.zip
    Auto Scalingncloud_autoscaling.zip
    Monitoringncloud_monitoring.zip
    Securityncloud_security.zip
    GeoLocationncloud_geolocation.zip
    CDN+ncloud_cdn_v2.zip
    Cloud DBncloud_clouddb_v2.zip
    Cloud Outbound Mailerncloud_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共通ヘッダに関する説明は、以下のとおりです。

    HeaderDescription
    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ステータスコードエラーコードエラーメッセージ説明
    400100Bad Request Exceptionプロトコル(HTTPS)、エンコード(UTF-8)などのリクエストエラー
    401200Authentication Failed認証失敗
    401210Permission Denied権限なし
    404300Not Found Exception権限なし
    429400Quota ExceededQuota超過
    429410Throttle LimitedRate超過
    429420Rate LimitedRate超過
    413430Request Entity Too Largeリクエストエンティティサイズの超過
    503500Endpoint Errorエンドポイント接続エラー
    504510Endpoint Timeoutエンドポイント接続時間の超過
    500900Unexpected 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.