[重要]API活用ガイド文書のサポート終了(Deprecated)のご案内
本API文書は、NAVERクラウドプラットフォームの拡張性あるAPIを提供するためにDeprecatedされ、 公式には使用されず、今後使用が停止する予定です。 (2018年12月)
新たに提供されるNcloud APIsガイドで、NAVERクラウドプラットフォームのAPI使用方法を確認してください。
=========================================== @deprecated 文書(~2018年12月) ==========================================
NAVERクラウドプラットフォームAPI概要
NAVERクラウドプラットフォームはNAVERの最新コンピューティング技術と運営ノウハウが蓄積されたクラウドサービスです。
NAVERクラウドプラットフォームから提供する様々な商品群の中からソリューション商品を利用できるように提供するアプリケーションインタフェース(API)を、NAVERクラウドプラットフォームAPIといいます。 NAVERクラウドプラットフォームAPIは、RESTful形式で提供され、HTTP方式のGET/POSTメソッド呼び出しを使用します。
APIリクエスト
API リクエストメッセージは、以下のように構成されます。
API リクエストの構成
API URL + アクション + アクションパラメータ + 応答フォーマット + AUTHPARMS
区分 | 説明 |
---|---|
API URL | NAVERクラウドプラットフォーム Server API URL https://api.ncloud.com/server/? https://api.ncloud.com/loadbalancer/? https://api.ncloud.com/cdn/? |
アクション | コンピューティングリソースリクエストアクション(作成、削除、照会など) action=createServerInstances |
アクションパラメータ | アクション関連パラメータ serverName=myserver&serverImageProductCode=SPSWLINUX000031 |
応答フォーマット | XML、JSON応答フォーマットをサポートし、オプション項目です。defaultは xml responseFormatType=xml |
AUTHPARAMS | oauth_consumer_key=CCe2T0ilv4aO3kIevT3x oauth_signature_method=HMAC-SHA1 oauth_version=1.0 oauth_timestamp=1392264315 oauth_nonce=9196882534520920143 oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%3D |
API リクエストSample
https://api.ncloud.com/cdn/?action=getGlobalCdnInstanceList&cdnInstanceNo=360654&responseFormatType=xml&oauth_consumer_key=FoIjXZEll1VpCC06A0Ll&oauth_nonce=-6974120256622557433&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1524378275&oauth_version=1.0&oauth_signature=6H0qtIpqxj%2FONQTQVVyooy22irI%3D
API リクエストSampleの構成
区分 | 説明 |
---|---|
https://api.ncloud.com/cdn/? | API URL |
action=getGlobalCdnInstanceList | アクション |
&cdnInstanceNo=360654 | アクションパラメータ |
&responseFormatType=xml | 応答フォーマット |
&oauth_consumer_key=FoIjXZEll1VpCC06A0Ll | AUTHPARAMS |
&oauth_nonce=-6974120256622557433 | AUTHPARAMS |
&oauth_signature_method=HMAC-SHA1 | AUTHPARAMS |
&oauth_timestamp=1524378275 | AUTHPARAMS |
&oauth_version=1.0 | AUTHPARAMS |
&oauth_signature=6H0qtIpqxj%2FONQTQVVyooy22irI%3D | AUTHPARAMS |
アクションパラメータ
基本的にKey、Value対で構成されており、リスト(List < Object >)形式のパラメータの場合、リスト型パラメータ名。N形式で構成されています。
一般的なアクションパラメータ
&cdnInstanceNo=1 &pageNo=1 …
リスト型アクションパラメータ
&domainIdList.1=CD000000000000006601 &domainIdList.2=CD000000000000006602 …
AUTHPARAMS
ここでは認証方法を簡単に説明します。 認証パラメータに関する詳しい内容は、ネイバークラウドプラットフォームOAuth利用ガイドをご参考ください。
認証キーを作成するために、下記の手順に従います。
base string 作成
- アクションパラメータにbase string作成に必要な認証パラメータを追加
- リクエストパラメータとvalue値をアルファベット順にソート
base string = RequestMethod + '&' + oauthEncode(requestUrl) + '&' + oauthEncode(queryString)
Java 作成例
private SortedMap<String, SortedSet<String>> getSignificateParametersForSiganturBaseString(Map<String, List<String>> requestParameters, String consumerKey) { SortedMap<String, SortedSet<String>> significateParameters = convertTypeToSortedMap(requestParameters); SortedSet<String> consumerKeySet = new TreeSet<String>(); consumerKeySet.add(consumerKey); significateParameters.put("oauth_consumer_key", consumerKeySet); SortedSet<String> nonceSet = new TreeSet<String>(); nonceSet.add(generateNonce()); significateParameters.put("oauth_nonce", nonceSet); SortedSet<String> signatureMethodSet = new TreeSet<String>(); signatureMethodSet.add("HMAC-SHA1"); significateParameters.put("oauth_signature_method", signatureMethodSet); SortedSet<String> timestampSet = new TreeSet<String>(); timestampSet.add(generateTimestamp()); significateParameters.put("oauth_timestamp", timestampSet); SortedSet<String> versionSet = new TreeSet<String>(); versionSet.add("1.0"); significateParameters.put("oauth_version", versionSet); return significateParameters; } private String makeSignatureBaseString(String requestMethod, String requestUrl, SortedMap<String, SortedSet<String>> significantParameters) { StringBuilder queryString = getRequestQueryString(significantParameters); requestUrl = normalizeUrl(requestUrl); requestUrl = OAuthCode3.oauthEncode(requestUrl); return new StringBuilder(requestMetho4.toUpperCase()).append('&').append(requestUrl).append('&').append(OAuthCode3.oauthEncode(queryString.toString())).toString(); }
base string 例
POST&http%3A%2F%2F10.101.54.72%2Fserver%2F&action%3DgetServerProductList%26oauth_consumer_key%3DCCe2T0ilv4aO3kIevT3x%26oauth_nonce%3D7179137053311691172%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1392277044%26oauth_version%3D1.0%26responseFormatType%3Dxml
署名書作成
Secret Keyと上で作成したbaseStringとHMAC SHA-1ハッシュアルゴリズムを用いて署名を作成します。
Java 作成例
private String sign(String signatureBaseString, String consumerSecret) throws NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeyException { Mac mac = Ma3.getInstance("HmacSHA1"); SecretKeySpec spec = new SecretKeySpec(new String(consumerSecret + "&").getBytes("UTF-8"), "HmacSHA1"); ma3.init(spec); byte text[] = signatureBaseString.getBytes("UTF-8"); byte signatureBytes[] = ma3.doFinal(text); signatureBytes = Base64.encodeBase64(signatureBytes); String signature = new String(signatureBytes, "UTF-8"); logger.debug("signature : " + signature); return signature; }
署名書例
vMissQDb84MhEn7NGh1+Yuyfank=
API 応答
APIの応答について説明します。
API 応答フォーマット
基本的にXML、JSON形式の応答フォーマットをサポートします。
XML 応答
<getGlobalCdnInstanceListResponse> <requestId>8452f415-88e7-4a23-8f45-40dded3e69e6</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <globalCdnInstanceList> <globalCdnInstance> <cdnInstanceNo>360654</cdnInstanceNo> <cdnInstanceStatus> <code>RUN</code> <codeName>Global CDN Run State</codeName> </cdnInstanceStatus> <cdnInstanceOperation> <code>NULL</code> ...
JSON 応答
{"getGlobalCdnInstanceListResponse": { "requestId": "78aec799-0e4f-4e6c-ac59-fa450af5e6ec", "returnCode": "0", "returnMessage": "success", "totalRows": 1, "globalCdnInstanceList": [ { "cdnInstanceNo": "360654", "cdnInstanceStatus": { "code": "RUN", "codeName": "Global CDN Run State" }, "cdnInstanceOperation": { "code": "NULL", "codeName": "Global CDN NULL OP" }, ...
NAVERクラウドプラットフォームのすべての応答はデータタイプで構成されています。 最初の応答タグは<アクション名+Response>形式で構成されています。
例えば、ProductListデータタイプに対する基本的な構成は以下の通りです。
CommonResponse |
---|
private String requestId; private String returnCode; private String returnMessage; |
ProductList extends CommonResponse |
---|
private List< Product > productList = new ArrayList< Product >(); |
Product |
---|
private String productCode; private String productName; private CommonCode productType; private String productDescription; private CommonCode infraResourceType; private Integer cpuCount; private Long memorySize; private Long baseBlockStorageSize; |
共通に伝達するCommonResponseデータタイプがProductListにextendsされており、ProductListはList
エラー処理
APIリクエストに誤りがあったり処理中にエラーが発生すると、エラー情報を応答でお伝えします。
不具合発生時HTTP応答コードは200 OK以外の値が配信され、また不具合情報は返還コード
ユーザーのエラーの例:HTTP応答コード400
<responseError> <returnCode>900</returnCode> <returnMessage> Required field is not specifie4. location : serverImageProductCode. </returnMessage> </responseError>
認証エラー例:HTTP応答コード401
<responseError> <returnCode>801</returnCode> <returnMessage>Signature is invalided</returnMessage> </responseError>
下記は HTTP 応答コード基準でソートしたエラー情報です。
HTTP 応答コード | 返還コード | 返還メッセージ |
---|---|---|
400 | 900 ~ 999 | パラメーターに関するエラー |
400 | 1100 | BAD REQUEST |
400 | 1400 ~ 1499 | ユーザーによって発生したその他のエラー |
400 | 10000 ~ 29999 | ユーザーによって発生したその他のエラー |
401 | 800 ~ 899 | 認証に関するエラー |
404 | 1101 | NOT FOUND |
405 | 1102 | METHOD NOT ALLOWED |
500 | 1000 ~ 1399 | サーバ内部エラー |
下記は、上記と同じエラー情報を返却コード基準で並び替えた表です。
HTTP 応答コード | 返還コード | 返還メッセージ |
---|---|---|
401 | 800 – 899 | 認証に関するエラー |
400 | 900 – 999 | パラメーターに関するエラー |
500 | 1000 – 1399 | サーバ内部エラー |
400 | 1100 | BAD REQUEST |
404 | 1101 | NOT FOUND |
405 | 1102 | METHOD NOT ALLOWED |
400 | 1400 – 1499 | ユーザーによって発生したその他のエラー |
400 | 10000 - 29999 | ユーザーによって発生したその他のエラー |
アクション
ここではアクションとアクションパラメータ情報および応答について記述します。
Exampleに使用される${CDN_Purge_API_URL}、NAVERクラウドプラットフォームサーバAPIのURL(https://api.ncloud.com/cdn/?)です。
getGlobalCdnInstanceList
API名
CDN インスタンスドメインリスト照会
説明
CDN 作成されたインスタンスドメインIDと情報を照会するAPIを提供します。
リクエストパラメータ
パラメータ名 | 簡略説明 | タイプ | 制約 | 必須 |
---|---|---|---|---|
cdnInstanceNo | CDN インスタンス番号 | String | - | No |
pageNo | ページ番号 | Integer | Min:0, Max:2147483647 | No |
pageSize | ページサイズ | Integer | Min:0, Max:2147483647 | No |
- cdnInstanceNo
CDNインスタンス番号を入力しない場合、アカウント内に生成されたすべてのインスタンスとドメインリスト情報が表示されます。
CDNインスタンス番号を入力すると、そのインスタンス内のドメインリスト情報のみ表示されます。 - pageNo
大量のCDNインスタンスリストを照会する時にPaginationのページ情報を入力します。
デフォルト値0に入力した場合、すべてのインスタンスを照会します。 - pageSize
大量のCDNインスタンスリストを照会すると、Paginationの表示されるインスタンス数を入力します。デフォルト値0に入力した場合、すべてのインスタンスを照会します。<br/>
- 例:pageNo=2&pageSize=10入力時2ページ内10個のCDNのインスタンスの一覧を照会します。
応答データタイプ
- GlobalCdnInstanceList タイプ
GlobalCdnInstanceList extends CommonResponse |
---|
private Integer totalRows; private List<GlobalCdnInstance> cdnInstanceList = new ArrayList<GlobalCdnInstance>(); |
GlobalCdnInstance |
---|
private String cdnInstanceNo; private CommonCode cdnInstanceStatus; private CommonCode cdnInstanceOperation; private String cdnInstanceStatusName; private Date createDate; private Date lastModifiedDate; private String cdnInstanceDescription; private String serviceName; private Boolean isAvailablePartialDomainPurge; private List<GlobalCdnServiceDomain> serviceDomainList = new ArrayList(); private GlobalCdnRule cdnRule = new GlobalCdnRule(); |
エラー
- API 応答 > エラー 処理 参考
例
リクエスト
${CDN_Purge_API_URL}?action=getGlobalCdnInstanceList &cdnInstanceNo=360654 &AUTHPARAMS
応答
<getGlobalCdnInstanceListResponse> <requestId>8452f415-88e7-4a23-8f45-40dded3e69e6</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <globalCdnInstanceList> <globalCdnInstance> <cdnInstanceNo>360654</cdnInstanceNo> <cdnInstanceStatus> <code>RUN</code> <codeName>Global CDN Run State</codeName> </cdnInstanceStatus> <cdnInstanceOperation> <code>NULL</code> <codeName>Global CDN NULL OP</codeName> </cdnInstanceOperation> <cdnInstanceStatusName>running</cdnInstanceStatusName> <createDate>2017-09-19T16:48:29+0900</createDate> <lastModifiedDate>2017-11-21T18:00:30+0900</lastModifiedDate> <cdnInstanceDescription>Access Log Enable</cdnInstanceDescription> <serviceName>test02-gcdn</serviceName> <isAvailablePartialDomainPurge>false</isAvailablePartialDomainPurge> <globalCdnServiceDomainList> <globalCdnServiceDomain> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>HTTP</protocolTypeCode> <defaultDomainName>myjuyrajgyga360654.gcdn.ntruss.com</defaultDomainName> <userDomainName></userDomainName> </globalCdnServiceDomain> </globalCdnServiceDomainList> <globalCdnRule> <protocolTypeCode>HTTP</protocolTypeCode> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <originUrl>ncp-cdn.origin.navercdn.com</originUrl> <originPath></originPath> <originHttpPort>80</originHttpPort> <originHttpsPort>0</originHttpsPort> <forwardHostHeaderTypeCode>REQUEST_HOST_HEADER</forwardHostHeaderTypeCode> <forwardHostHeader></forwardHostHeader> <cacheKeyHostNameTypeCode>REQUEST_HOST_HEADER</cacheKeyHostNameTypeCode> <isGzipCompressionUse>true</isGzipCompressionUse> <cachingOptionTypeCode>CACHE_CONTROL_AND_EXPIRES</cachingOptionTypeCode> <isErrorContentsResponseUse>false</isErrorContentsResponseUse> <cachingTtlTime>604800</cachingTtlTime> <isQueryStringIgnoreUse>true</isQueryStringIgnoreUse> <isRemoveVaryHeaderUse>true</isRemoveVaryHeaderUse> <isLargeFileOptimizationUse>false</isLargeFileOptimizationUse> <gzipResponseTypeCode>ORIGIN_RESPONSE</gzipResponseTypeCode> <isReferrerDomainUse>false</isReferrerDomainUse> <referrerDomainList/> <isReferrerDomainRestrictUse>false</isReferrerDomainRestrictUse> <isSecureTokenUse>false</isSecureTokenUse> <secureTokenPassword></secureTokenPassword> <isReissueSecureTokenPassword>false</isReissueSecureTokenPassword> <isAccessLogUse>true</isAccessLogUse> <accessLogFileStorageContainerName>globalcdn-logs</accessLogFileStorageContainerName> </globalCdnRule> </globalCdnInstance> </globalCdnInstanceList> </getGlobalCdnInstanceListResponse>
requestGlobalCdnPurge
API名
CDN Purge リクエスト
説明
CDNの特定のインスタンスに対して全体ファイル、個別ファイルのPurgeを遂行するAPIです。
リクエストパラメータ
パラメータ名 | 簡略説明 | タイプ | 制約 | 必須 |
---|---|---|---|---|
cdnInstanceNo | CDN インスタンス番号 | String | - | Yes |
serviceDomainNameList.N | ドメインIDリスト | String | - | No |
isWholePurge | 全体パージ可否 | Boolean | - | Yes |
isWholeDomain | 全体ドメイン可否 | Boolean | - | Yes |
targetFileList.N | パージ対象のファイルリスト | String | - | No |
- cdnInstanceNo
Purgeを実行する対象のCDNインスタンス番号を入力します。 - serviceDomainNameList.N
CDNインスタンス内のPurgeを実行するドメインリストを入力します。 - isWholePurge
CDNインスタンス内のキャッシングされたすべてのコンテンツをPurgeする場合、"true"を入力します。<b>全体のパージを実行する場合、原本にリクエスト/トラフィックの増加により負荷が発生する可能性があり、使用を勧告しません。</b>
- isWholeDomain
CDNインスタンス内の全てのドメインに対してPurgeする場合、"true"を入力します。CDNインスタンス情報照会時、"isAvailablePartialDomainPurge"の値が"false"の場合は、"true"でのみ入力する必要があります。
- targetFileList.N
個別のファイル単位Purgeの実行時、対象のファイルリストを入力します。
応答データタイプ
- GlobalCdnPurgeHistoryList
GlobalCdnPurgeHistoryList extends CommonResponse |
---|
private Integer totalRows; private List<GlobalCdnPurgeHistory> globalCdnPurgeHistoryList = new ArrayList<GlobalCdnPurgeHistory>(); |
GlobalCdnPurgeHistory |
---|
private String cdnInstanceNo; private String purgeId; private Boolean isWholePurge; private Boolean isWholeDomainPurge; private List<GlobalCdnServiceDomain> serviceDomainList = new ArrayList(); private List<String> targetFileList = new ArrayList(); private Date requestDate; private Date estimatedCompletionDate; private Boolean isSuccess; |
エラー
- API 応答 > エラー処理 参考
例
リクエスト
${CDN_Purge_API_URL}?action=requestGlobalCdnPurge &cdnInstanceNo=360654&isWholeDomain=true&isWholePurge=false &targetFileList.1%2Fsample_img.jpg&targetFileList.2=%2Fsample_mv.mp4 &targetFileList.3=%2Fsample_test.jpg &AUTHPARAMS
応答
<requestGlobalCdnPurgeResponse> <requestId>bf0ce15d-dad1-46c7-8b98-5cadd7b1f024</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <globalCdnPurgeHistoryList> <globalCdnPurgeHistory> <cdnInstanceNo>360654</cdnInstanceNo> <purgeId>4c0fd940-4608-11e8-81c3-8fe11a63f981</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <globalCdnServiceDomainList> <globalCdnServiceDomain> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode></protocolTypeCode> <defaultDomainName>myjuyrajgyga360654.gcdn.ntruss.com</defaultDomainName> <userDomainName></userDomainName> </globalCdnServiceDomain> </globalCdnServiceDomainList> <targetFileList> <string>/sample_img.jpg</string> <string>/sample_mv.mp4</string> <string>/sample_test.jpg</string> </targetFileList> <estimatedCompletionDate>2018-04-22T17:36:53+0900</estimatedCompletionDate> <isSuccess>true</isSuccess> <requestDate>2018-04-22T17:36:48+0900</requestDate> </globalCdnPurgeHistory> </globalCdnPurgeHistoryList> </requestGlobalCdnPurgeResponse>
getGlobalCdnPurgeHistoryList
API名
CDN Purge 履歴照会
説明
CDN Purge 実行結果と履歴を照会するAPIです。
リクエストパラメータ
パラメータ名 | 簡略説明 | タイプ | 制約 | 必須 |
---|---|---|---|---|
cdnInstanceNo | CDN インスタンス番号 | String | - | Yes |
purgeIdList.N | Purge ID リスト | String | - | No |
- cdnInstanceNo
Purgeを実行した対象CDNインスタンス番号を入力します。 - purgeIdList.N
Purgeリクエスト時に応答したPurge ID情報を入力します。Purge ID、米入力時、最近実行した5つのPurgeの履歴情報を確認することができます。
応答データタイプ
- GlobalCdnPurgeHistoryList
GlobalCdnPurgeHistoryList extends CommonResponse |
---|
private Integer totalRows; private List<GlobalCdnPurgeHistory> globalCdnPurgeHistoryList = new ArrayList<GlobalCdnPurgeHistory>(); |
GlobalCdnPurgeHistory |
---|
private String cdnInstanceNo; private String purgeId; private Boolean isWholePurge; private Boolean isWholeDomainPurge; private List<GlobalCdnServiceDomain> serviceDomainList = new ArrayList(); private List<String> targetFileList = new ArrayList(); private Date requestDate; private Date estimatedCompletionDate; private Boolean isSuccess; |
エラー
- API 応答 > エラー処理 参考
例
リクエスト
${CDN_Purge_API_URL}?action=getGlobalCdnPurgeHistoryList &cdnInstanceNo=360654&purgeIdList.1=4c0fd940-4608-11e8-81c3-8fe11a63f981 &AUTHPARAMS
応答
<getGlobalCdnPurgeHistoryListResponse> <requestId>9b9a210d-72e4-46a8-86c3-ec49bb4344eb</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <globalCdnPurgeHistoryList> <globalCdnPurgeHistory> <cdnInstanceNo>360654</cdnInstanceNo> <purgeId>4c0fd940-4608-11e8-81c3-8fe11a63f981</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <globalCdnServiceDomainList> <globalCdnServiceDomain> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode></protocolTypeCode> <defaultDomainName>myjuyrajgyga360654.gcdn.ntruss.com</defaultDomainName> <userDomainName></userDomainName> </globalCdnServiceDomain> </globalCdnServiceDomainList> <targetFileList> <string>/sample_img.jpg</string> <string>/sample_mv.mp4</string> <string>/sample_test.jpg</string> </targetFileList> <estimatedCompletionDate>2018-04-22T17:36:53+0900</estimatedCompletionDate> <isSuccess>true</isSuccess> <requestDate>2018-04-22T17:36:48+0900</requestDate> </globalCdnPurgeHistory> </globalCdnPurgeHistoryList> </getGlobalCdnPurgeHistoryListResponse>
関連情報リンク
次のガイドから関連情報が確認できます。