--- title: "Ncloud API" slug: "common-ncpapi" updated: 2026-09-17T09:56:55Z published: 2026-09-17T09:56:55Z canonical: "api.ncloud-docs.com/common-ncpapi" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Ncloud API Classic/VPC環境で利用できます。 NAVERクラウドプラットフォームの APIは RESTful APIとして提供され、JSONと XML形式で返します。アクションに応じてパラメータ値を入力して登録、変更、削除、照会でき、サービスと運営ツールの自動化にも活用できます。HTTPでメソッドを呼び出し、呼び出しに失敗するとエラーコードとメッセージを返します。Ncloud APIには、互換 APIと連携 APIを除く、NAVERクラウドプラットフォームのすべての APIが該当します。 参考 Ncloud APIの一部内容は、互換 APIと連携 APIにも該当するので、サービス別 APIガイドを参照してご使用ください。 ## API認証キー NAVERクラウドプラットフォーム APIは、権限を持つユーザーのみ呼び出すことができるようにユーザー識別ツールである API認証キーを`Access key`と`Secret key`のワンセットで構成して、アカウント別に発行しています。これは API呼び出しの認証時に渡されるパラメータとして使用します。そのため、NAVERクラウドプラットフォームの APIを使用するには、まず認証キーを作成する必要があります。 認証キーの作成と管理は NAVERクラウドプラットフォームのコンソールで行います。NAVERクラウドプラットフォームコンソールで認証キーを作成・管理する方法は、次の通りです。 1. NAVERクラウドプラットフォームコンソールにログインします。 2. コンソール画面右上にある **My Account** > **アカウントとセキュリティ管理**メニューを順にクリックします。 3. 再ログイン認証画面が表示されたら、パスワードを入力し、 **[確認]** ボタンをクリックします。 4. **セキュリティ管理** > **アクセス管理**メニューを順にクリックします。 5. **API認証キーの管理**でデフォルトで提供される **Access key ID**と **Secret key**を確認します。 6. 必要な操作を行います。 - API認証キーの追加発行 - **[新規 API認証キーを作成]** ボタンをクリック - API認証キーの使用停止 - **[使用停止]** ボタンをクリック - 使用停止した認証キーを再び使用するには、 **[使用]** ボタンをクリック - API認証キーの削除 - **[削除]** ボタンをクリック - 使用停止した認証キーのみ削除可能 参考 - NAVERクラウドプラットフォームの API認証キーは、NAVERクラウドプラットフォームのアカウントを作成する際、自動で1つ作成されます。自動作成された認証キーに加えて、ユーザーがポータルから直接作成することもできるため、ユーザーごとに最大2つの認証キーを発行できます。 - 認証キーを使用停止または削除した場合、有効ではないキーとして認識され、認証に使用できなくなります。 ## 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 ``` #### リクエストヘッダ NAVERクラウドプラットフォーム APIの共通ヘッダは、認証関連のフィールドを含みます。リクエストヘッダの説明は次の通りです。 参考 サービス別 APIのヘッダ構成は異なる場合がありますので、サービス別 APIガイドをご参照ください。 | フィールド | 必須の有無 | 説明 | | --- | --- | --- | | `x-ncp-apigw-timestamp` | Required | 1970年1月1日00:00:00協定世界時(UTC)からの経過時間(ミリ秒)API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす | | `x-ncp-iam-access-key` | Required | NAVERクラウドプラットフォームから発行された Access KeyAccess Keyの発行と確認: [認証キーの作成](/docs/ja/common-ncpapi#1%EC%9D%B8%EC%A6%9D%ED%82%A4%EC%83%9D%EC%84%B1)を参照サブアカウントの Access Key発行と確認: [サブアカウントの作成](https://guide.ncloud-docs.com/docs/ja/subaccount-use#%EC%84%9C%EB%B8%8C-%EA%B3%84%EC%A0%95-%EC%83%9D%EC%84%B1)を参照 | | `x-ncp-apigw-signature-v2` | Required | NAVERクラウドプラットフォームから発行された Access Keyとマッピングする Secret Keyと HMAC暗号化アルゴリズム(HmacSHA256)でリクエスト情報を暗号化した後、Base64でエンコードした署名Secret Keyの発行と確認: [認証キーの作成](/docs/ja/common-ncpapi#1%EC%9D%B8%EC%A6%9D%ED%82%A4%EC%83%9D%EC%84%B1)を参照署名の作成: [シグネチャーの作成](/docs/ja/common-ncpapi#2%ED%97%A4%EB%8D%94)を参照 | 注意 `x-ncp-apigw-timestamp`は、シグネチャー作成時に入力した timestampと必ず一致しなければなりません。 参考 NAVERクラウドプラットフォームの APIの V1バージョンでは、アカウント別 Keyを発行して認証に活用する API Key認証方式を使用していました。そのため、APIの呼び出し時に API Keyをヘッダに含める必要がありましたが、2022年1月1日からは V1バージョンのサービスを終了し、API Keyの適用が不要な V2バージョンで提供しています。V2バージョンは、オペレーションおよび基本呼び出し方式が V1バージョンと同じですが、APIを呼び出す際に API Keyをヘッダに含める必要がないため、API Gatewayを申し込まなくてもよいので、利用が簡単であるという利点があります。 ただし、一部のサービスでは、API Keyによる認証方式が必要な場合がありますので、各サービスの APIガイドで API Keyの必須適用有無を確認した上でご使用ください。 - API Keyは、NAVERクラウドプラットフォームの API Gatewayで作成できます。作成方法の詳細は、[API Gatewayご利用ガイド](https://guide.ncloud-docs.com/docs/ja/apigw-apigw-1)をご参照ください。 - API Gatewayで API keyを発行することに対して別途の料金は発生しません。 #### リクエスト例 認証キーと共通ヘッダを使用したリクエストのサンプルコードは次の通りです。 ``` 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}' \ ``` ### レスポンス 共通レスポンス形式を説明します。 参考 サービス別 APIのレスポンス形式は異なる場合がありますので、サービス別 APIガイドをご参照ください。 #### レスポンスステータスコード レスポンスステータスコードの説明は次の通りです。 | HTTPステータスコード | コード | メッセージ | 説明 | | --- | --- | --- | --- | | 200 | - | OK | リクエスト成功 | | 201 | - | Created | リクエストの結果により新しいリソースが作成される | | 202 | - | Accepted | リクエストは受付されたが、まだ完了していない | | 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`) ``` { "status": { "code": "20000", "message": "OK" }, "result": {...} } ``` - 成功(`Content-type: application/xml`) ``` 20000 OK ... ``` - 失敗(`Content-type: application/json`) ``` { "error":{ "errorCode":"210", "message":"Permission Denied" } } ``` - 失敗(`Content-type: application/xml`) ``` 210 Permission Denied ``` 参考 レスポンス形式のデフォルトは JSONです。 ## APIのセキュリティ設定 API認証キーが第三者に流出する場合、リソースを任意に変更したり照会することができるため、セキュリティ上の深刻な問題が発生する可能性があるので、適切な事前準備と対応が必要です。 ### API認証キーの再発行 API認証キーを使用していないか、盗用が疑われる場合は、発行した認証キーを使用停止するか、削除した後、再発行してください。 ### サブアカウント認証キーの使用 すべての権限を持つメインアカウントでないサブアカウントで API認証キーを発行して APIを呼び出し、認証キーの流出に備えて定期的に交換することもできます。サブアカウントはロールに合った権限だけ付与され使用することができます。さらに、IPアドレス帯域だけでなく、VPCまで API Access Sourceの指定が可能なため、セキュリティ上より安全に APIを使用できます。 サブアカウントは、NAVERクラウドプラットフォームの Sub Accountサービスで作成します。サブアカウントと API認証キーの作成方法は、[Sub Accountご利用ガイド](https://guide.ncloud-docs.com/docs/ja/subaccount-overview)をご参照ください。 ### APIアクセス制限の設定 許可されていない位置からの API Gatewayアクセスをブロックするために、特定の IPアドレス帯域からのみ使用できるように設定できます。特定の IPアドレス帯域でのみ APIを使用できるように設定する方法は、次の通りです。 1. NAVERクラウドプラットフォームコンソールにログインします。 2. **My Account** > **アカウントとセキュリティ管理** > **セキュリティ管理** > **アクセス管理**メニューを順にクリックします。 3. **APIアクセス制限の設定**の **IP Address**にアクセスを許可する IPアドレス帯域を入力します。 - [CIDR表記](/docs/ja/common-ncpapi#CIDR%ED%91%9C%EA%B8%B0%EB%B2%95)を参照して入力してください。 - 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)表記を使用して入力する方法もサポートします。 ![common-ncpapi_01_ko](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/common-ncpapi_01_ja.png?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) CIDRは、連続した IPアドレス範囲を表記する方法の1つです。CIDR表記は、IPアドレスを Net ID(Network ID)と Host IDに区分し、Net IDの下位に属する IPアドレス帯域(Host IDカテゴリ)をグループ化して表現することができます。これを Address Aggregation/Supernettingともいいます。 ![common-ncpapi_02_ko](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/common-ncpapi_02_ja.png?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) 一般に使用する IPアドレスは次のように4オクテット(Octet)で構成されています。 | CIDR | Octet | Octet | Octet | Octet | Range | IP Address Band | Hosts | | --- | --- | --- | --- | --- | --- | --- | --- | | 192.168.0.0/24 | 192 | 168 | 0 | 0 | 24 | 192.168.0.0 ~ 192.168.0.255 | 256 | | 192.168.10.23/30 | 192 | 168 | 10 | 23 | 30 | 192.168.10.20 ~ 192.168.10.23 | 4 | | 192.168.23.11/32 | 192 | 168 | 23 | 11 | 32 | 192.168.23.11 ~ 192.168.23.11 | 1 | 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の入力範囲は24~32です。 各 Rangeに対応する Hostの IPアドレス数は次の通りです。 | Range | Class | Hosts | | --- | --- | --- | | /32 | 1/256 C | 1 | | /31 | 1/128 C | 2 | | /30 | 1/64 C | 4 | | /29 | 1/32 C | 8 | | /28 | 1/16 C | 16 | | /27 | 1/8 C | 32 | | /26 | 1/4 C | 64 | | /25 | 1/2 C | 128 | | /24 | 1 C | 256 | 注意 入力行を追加すると Rangeは Default/32(単一の IPアドレス)に設定され、変更できるようになるので入力時はご注意ください。 ## サポート APIと SDK NAVERクラウドプラットフォームがサポートする APIと SDK情報をご案内します。 ### API 各サービスがサポートする APIリストは、サービス別 APIガイドで確認してください。 ### SDK 各サービスがサポートする SDKリストとダウンロードリンクは、次の通りです。 | サービス | SDKのダウンロード | | --- | --- | | Server | [ncloud_server.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_server_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Load Balancer | [ncloud_loadbalancer.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_loadbalancer_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Auto Scaling | [ncloud_autoscaling.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_autoscaling_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Monitoring | [ncloud_monitoring.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_monitoring_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Security | [ncloud_security.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_security_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Cloud DB | [ncloud_clouddb_v2.zip](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_clouddb_v2.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) | | Cloud Outbound Mailer | [**ダウンロード**](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/ncloud_outboundmailer_v1.6.1.zip?sv=2026-02-06&spr=https&st=2026-10-26T08%3A55%3A05Z&se=2026-10-26T09%3A55%3A05Z&sr=c&sp=r&sig=d1tWRQJ5AeYzpVMQvEbRD2b8Z3c43gn3Ol5FHsN8cko%3D) |