[중요] API 활용 가이드 문서 지원 종료 (Deprecated) 안내
본 API 문서는 네이버 클라우드 플랫폼의 확장성 있는 API 제공을 위해 Deprecated 되어 공식적으로 사용하지 않으며, 앞으로 사용이 정지될 예정입니다. (2018년 12월)
새롭게 제공되는 Ncloud APIs 가이드에서 네이버 클라우드 플랫폼의 API 사용 방법을 확인해 주십시오.
=========================================== @deprecated 문서(~2018년12월) ==========================================
네이버 클라우드 플랫폼 API 개요
네이버 클라우드 플랫폼은 NAVER의 최신 컴퓨팅 기술과 운영 노하우가 축적된 클라우드 서비스입니다.
네이버 클라우드 플랫폼에서 제공하는 여러 가지 상품군 중에서 솔루션 상품을 이용할 수 있도록 제공하는 응용 프로그램 인터페이스(API)를 네이버 클라우드 플랫폼 API라고 합니다. 네이버 클라우드 플랫폼 API는 RESTful 형태로 제공되며 HTTP 방식의 GET/POST 메서드 호출을 사용합니다.
API 요청
API 요청 메시지는 아래와 같이 구성됩니다.
API 요청 구성
API URL + 액션 + 액션 파라미터 + 응답 포맷 + AUTHPARMS
구분 | 설명 |
---|---|
API URL | 네이버 클라우드 플랫폼 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=getCdnPlusInstanceList&cdnInstanceNo=354360&responseFormatType=xml&oauth_consumer_key=CCe2T0ilv4aO3kIevT3x&oauth_nonce=9196882534520920143&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1392264315&oauth_version=1.0&oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%3D
API 요청 Sample 구성
구분 | 설명 |
---|---|
https://api.ncloud.com/cdn/? | API URL |
action=getCdnPlusInstanceList | 액션 |
&cdnInstanceNo=354360 | 액션파라미터 |
&responseFormatType=xml | 응답포맷 |
&oauth_consumer_key=CCe2T0ilv4aO3kIevT3x | AUTHPARAMS |
&oauth_nonce=9196882534520920143 | AUTHPARAMS |
&oauth_signature_method=HMAC-SHA1 | AUTHPARAMS |
&oauth_timestamp=1392264315 | AUTHPARAMS |
&oauth_version=1.0 | AUTHPARAMS |
&oauth_signature=rtKrFoEAHqRFTqon5vt4fObtv%2F8%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 응답
<getCdnPlusInstanceListResponse> <requestId>8d6a5116-d692-43a6-9f6d-df8678e3baf9</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <cdnInstanceList> <cdnPlusInstance> <cdnInstanceNo>354360</cdnInstanceNo> <cdnInstanceStatus> <code>RUN</code> <codeName>Server RUN State</codeName> </cdnInstanceStatus> <cdnInstanceOperation> <code>NULL</code> ...
json 응답
{"getCdnPlusInstanceListResponse": { "requestId": "27535776-86fd-457a-b8ff-27cb28fba20a", "returnCode": "0", "returnMessage": "success", "totalRows": 1, "cdnInstanceList": [ { "cdnInstanceNo": "354360", "cdnInstanceStatus": { "code": "RUN", "codeName": "Server RUN State" }, "cdnInstanceOperation": { "code": "NULL", "codeName": "Server NULL OP" }, ...
네이버 클라우드 플랫폼의 모든 응답은 데이터 타입으로 구성되어 있습니다. 첫 Response 태그는 < 액션명+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< Product >으로 구성되어 있습니다.
오류 처리
API 요청이 잘못되거나 처리 도중 오류가 발생하면 오류 정보를 응답으로 전달합니다.
오류 발생 시 HTTP 응답 코드는 200 OK 외의 값이 전달되며, 오류 정보는 반환 코드 < returnCode >와 반환 메시지 < returnMessage >로 구성되며, CommonResponse 데이터 타입을 가집니다. 또한 모든 오류는 < responseError >라는 이름으로 반환됩니다.
사용자 오류 예: 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}은 네이버 클라우드 플랫폼 모니터링 API URL(https://api.ncloud.com/cdn/?)입니다.
getCdnPlusInstanceList
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으로 입력한 경우 모든 인스턴스를 조회합니다.- 예시) pageNo=2&pageSize=10 입력 시 : 2페이지 내 10개의 CDN 인스턴스 목록을 조회합니다.
응답 데이터 타입
- CdnPlusInstanceList 타입
CdnPlusInstanceList extends CommonResponse |
---|
private Integer totalRows; private List<CdnPlusInstance> cdnInstanceList = new ArrayList<CdnPlusInstance>(); |
CdnPlusInstance |
---|
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 isForLiveTranscoder; private List<String> liveTranscoderInstanceNoList = new ArrayList(); private Boolean isAvailablePartialDomainPurge; private List<CdnPlusServiceDomain> serviceDomainList = new ArrayList(); private CdnPlusRule cdnRule = new CdnPlusRule(); |
오류
- API 응답 > 오류 처리 참고
예시
요청
${CDN_Purge_API_URL}?action=getCdnPlusInstanceList &cdnInstanceNo=354261 &AUTHPARAMS
응답
<getCdnPlusInstanceListResponse> <requestId>e620cda2-801d-40a4-88f9-cacca9be952e</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <cdnInstanceList> <cdnPlusInstance> <cdnInstanceNo>354261</cdnInstanceNo> <cdnInstanceStatus> <code>RUN</code> <codeName>Server RUN State</codeName> </cdnInstanceStatus> <cdnInstanceOperation> <code>NULL</code> <codeName>Server NULL OP</codeName> </cdnInstanceOperation> <cdnInstanceStatusName>running</cdnInstanceStatusName> <createDate>2017-08-30T15:37:43+0900</createDate> <lastModifiedDate>2017-08-30T16:10:11+0900</lastModifiedDate> <cdnInstanceDescription/> <serviceName>cdn-test001</serviceName> <isForLiveTranscoder>false</isForLiveTranscoder> <liveTranscoderInstanceNoList/> <isAvailablePartialDomainPurge>false</isAvailablePartialDomainPurge> <serviceDomainList> <cdnPlusServiceDomain> <domainId>CD000000000000006588</domainId> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>ALL</protocolTypeCode> <defaultDomainName>ldkdbllrrfoc354261dev.cdn.ntruss.com</defaultDomainName> <userDomainName/> </cdnPlusServiceDomain> </serviceDomainList> </cdnPlusInstance> </cdnInstanceList> </getCdnPlusInstanceListResponse>
requestCdnPlusPurge
API명
CDN Purge 요청
설명
CDN 특정 인스턴스에 대하여 전체 파일, 디렉토리 단위, 개별 파일에 대한 Purge를 수행하는 API입니다.
요청 파라미터
파라미터명 | 간략 설명 | 타입 | 제약 | 필수 여부 |
---|---|---|---|---|
cdnInstanceNo | CDN 인스턴스 번호 | String | - | Yes |
domainIdList.N | 도메인ID 리스트 | String | - | No |
isWholePurge | 전체 퍼지 여부 | Boolean | - | Yes |
isWholeDomain | 전체 도메인 여부 | Boolean | 인스턴스 정보와 일치 필요 | Yes |
targetFileList.N | 퍼지 대상 파일 리스트 | String | Max:100개 | No |
targetDirectoryName | 퍼지 대상 디렉토리명 | String | - | No |
cdnInstanceNo
Purge를 수행할 대상 CDN 인스턴스 번호를 입력합니다.domainIdList.N
CDN 인스턴스 내 Purge를 수행할 도메인 리스트를 입력합니다.isWholePurge
CDN 인스턴스 내 캐싱된 모든 콘텐츠를 Purge할 경우 'true'를 입력합니다.
전체 퍼지를 수행할 경우 원본에 요청/트래픽이 증가로 부하가 발생할 수 있어 사용을 권고하지 않습니다.isWholeDomain
CDN 인스턴스 내 모든 도메인에 대하여 Purge할 경우 'true'를 입력합니다.
CDN 인스턴스 정보 조회 시 'isAvailablePartialDomainPurge'의 값이 'false'인 경우에는 'true'로만 입력해야 합니다.targetFileList.N
개별 파일 단위 Purge 수행 시 대상의 파일 리스트를 입력합니다.
파일은 한번에 100개까지만 수행할 수 있습니다.targetDirectoryName
디렉토리 Purge 수행 시 대상 디렉토리명을 입력합니다.
응답 데이터 타입
- CdnPlusPurgeHistoryList
CdnPlusPurgeHistoryList extends CommonResponse |
---|
private Integer totalRows; private List<CdnPlusPurgeHistory> cdnPlusPurgeHistoryList = new ArrayList<CdnPlusPurgeHistory>(); |
CdnPlusPurgeHistory |
---|
private String cdnInstanceNo; private String purgeId; private Boolean isWholePurge; private Boolean isWholeDomain; private List<CdnPlusServiceDomain> serviceDomainList = new ArrayList(); private String targetDirectoryName; private List<String> targetFileList = new ArrayList(); private Date requestDate; private String purgeStatusName; |
오류
- API 응답 > 오류 처리 참고
예시
요청
${CDN_Purge_API_URL}?action=requestCdnPlusPurge &cdnInstanceNo=354261&isWholeDomain=true&isWholePurge=false &targetFileList.1%2Fsample_img.jpg&targetFileList.2=%2Fsample_mv.mp4 &targetFileList.3=%2Fsample_test.jpg &AUTHPARAMS
응답
<requestCdnPlusPurgeResponse> <requestId>e7998900-4fc1-4a8e-81dc-0171a9ae7a57</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>1</totalRows> <purgeHistoryList> <cdnPlusPurgeHistory> <cdnInstanceNo>354261</cdnInstanceNo> <purgeId>PT000000000000000540</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <serviceDomainList> <cdnPlusServiceDomain> <domainId>CD000000000000006588</domainId> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>ALL</protocolTypeCode> <defaultDomainName>ldkdbllrrfoc354261dev.cdn.ntruss.com</defaultDomainName> <userDomainName/> </cdnPlusServiceDomain> </serviceDomainList> <targetDirectoryName/> <targetFileList> <string>/sample_img.jpg</string> <string>/sample_mv.mp4</string> <string>/sample_test.jpg</string> </targetFileList> <requestDate>2018-02-24T13:26:29+0900</requestDate> <purgeStatusName>ready</purgeStatusName> </cdnPlusPurgeHistory> </purgeHistoryList> </requestCdnPlusPurgeResponse>
getCdnPlusPurgeHistoryList
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 이력 정보를 확인할 수 있습니다.
응답 데이터 타입
- CdnPlusPurgeHistoryList
CdnPlusPurgeHistoryList extends CommonResponse |
---|
private Integer totalRows; private List<CdnPlusPurgeHistory> cdnPlusPurgeHistoryList = new ArrayList<CdnPlusPurgeHistory>(); |
CdnPlusPurgeHistory |
---|
private String cdnInstanceNo; private String purgeId; private Boolean isWholePurge; private Boolean isWholeDomain; private List<CdnPlusServiceDomain> serviceDomainList = new ArrayList(); private String targetDirectoryName; private List<String> targetFileList = new ArrayList(); private Date requestDate; private String purgeStatusName; |
오류
- API 응답 > 오류 처리 참고
예시
요청
${CDN_Purge_API_URL}?action=getCdnPlusPurgeHistoryList &cdnInstanceNo=354261&purgeIdList.1=PT000000000000000540 &AUTHPARAMS
응답
<getCdnPlusPurgeHistoryListResponse> <requestId>0eb9ec73-1df4-4c64-9e32-9643561e3b27</requestId> <returnCode>0</returnCode> <returnMessage>success</returnMessage> <totalRows>3</totalRows> <purgeHistoryList> <cdnPlusPurgeHistory> <cdnInstanceNo>354261</cdnInstanceNo> <purgeId>PT000000000000000540</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <serviceDomainList> <cdnPlusServiceDomain> <domainId>CD000000000000006588</domainId> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>ALL</protocolTypeCode> <defaultDomainName>ldkdbllrrfoc354261dev.cdn.ntruss.com</defaultDomainName> <userDomainName/> </cdnPlusServiceDomain> </serviceDomainList> <targetDirectoryName/> <targetFileList> <string>/sample_img.jpg</string> </targetFileList> <requestDate>2018-02-24T13:26:29+0900</requestDate> <purgeStatusName>success</purgeStatusName> </cdnPlusPurgeHistory> <cdnPlusPurgeHistory> <cdnInstanceNo>354261</cdnInstanceNo> <purgeId>PT000000000000000540</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <serviceDomainList> <cdnPlusServiceDomain> <domainId>CD000000000000006588</domainId> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>ALL</protocolTypeCode> <defaultDomainName>ldkdbllrrfoc354261dev.cdn.ntruss.com</defaultDomainName> <userDomainName/> </cdnPlusServiceDomain> </serviceDomainList> <targetDirectoryName/> <targetFileList> <string>/sample_mv.mp4</string> </targetFileList> <requestDate>2018-02-24T13:28:31+0900</requestDate> <purgeStatusName>success</purgeStatusName> </cdnPlusPurgeHistory> <cdnPlusPurgeHistory> <cdnInstanceNo>354261</cdnInstanceNo> <purgeId>PT000000000000000540</purgeId> <isWholePurge>false</isWholePurge> <isWholeDomain>true</isWholeDomain> <serviceDomainList> <cdnPlusServiceDomain> <domainId>CD000000000000006588</domainId> <serviceDomainTypeCode>DEFAULT</serviceDomainTypeCode> <protocolTypeCode>ALL</protocolTypeCode> <defaultDomainName>ldkdbllrrfoc354261dev.cdn.ntruss.com</defaultDomainName> <userDomainName/> </cdnPlusServiceDomain> </serviceDomainList> <targetDirectoryName/> <targetFileList> <string>/sample_test.jpg</string> </targetFileList> <requestDate>2018-02-24T13:29:45+0900</requestDate> <purgeStatusName>success</purgeStatusName> </cdnPlusPurgeHistory> </purgeHistoryList> </getCdnPlusPurgeHistoryListResponse>
연관 정보 바로가기
아래 가이드에서 연관 정보를 확인할 수 있습니다.