VOD Transcoder API를 사용하기 전에

VOD Transcoder API는 HTTP API 형태로 제공됩니다.

VOD Transcoder API를 호출하기 위해서는 API Gateway 인증을 반드시 수행해야 합니다. 자세한 API Gateway 사용 방법은 "API Gateway 설명서(구, 사용자 가이드)"를 참고하세요.

제약사항

VOD Transocder API v1은 초당 12회의 요청 수 제한이 적용됩니다.

API 인증키 발급

VOD Transcoder API는 네이버 클라우드 플랫폼 API Gateway를 통하여 제공됩니다. API Gateway에 등록된 API를 사용하기 위해서는 3가지 인증키(Access Key ID, Secret Key, API Key)를 발급받아야 합니다.

API 인증키 발급에 대한 자세한 내용은 "API GATEWAY 사용자 가이드"를 참고하세요.

  • 인증키 생성
    • 네이버 클라우드 플랫폼 포털의 마이페이지 > 계정관리 > 인증키 관리 메뉴에서 신규 API 인증키 생성을 클릭하여 Access Key ID, Secret Key를 생성합니다.
    • 만약 Access Key ID, Secret Key가 있다면 해당 키를 사용합니다.
  • API Key 생성
    • Console의 API Gateway 메뉴에서 API Key 생성을 클릭하여 API Key를 생성합니다.

API 호출하기

API 요청 메시지는 아래와 같이 구성되며, 발급받은 인증키(Access Key ID, Secret Key, API Key)를 참고하여 사용합니다.

API 호출 구성

{METHOD} {API URL}/{ACTION}?{ACTION PARAMS} + AUTHPARMS(header)
구분 정의
METHOD GET/POST/DELETE
API URL VOD Transcoder API URL
https://vodtranscoder.apigw.ntruss.com/api/v1
ACTION Job 생성, Job 목록 조회, Job 정보 조회, 프리셋 목록 조회, 프리셋 정보 조회
ACTION PARAMS Job 목록 조회 시 사용
(예: startTime=1520089200&endTime=1522767600&limit=10&offset=1)
AUTHPARAMS Request header에 인증키를 추가
(x-ncp-apigw-api-key, x-ncp-apigw-timestamp, x-ncp-iam-access-key, x-ncp-apigw-signature-v1)

ACTION PARAMS

기본적으로 Key, Value 쌍으로 구성되어 있습니다.

  • 예시
&limit=1
&offset=10
…

AUTHPARAMS 생성하기

Header Description
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타냄
APIGW 서버와 시간차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-apigw-api-key API Gateway에서 발급받은 키
x-ncp-iam-access-key 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID
x-ncp-apigw-signature-v1 위 예제의 Body를 Access Key ID와 맵핑되는 Secret Key로 암호화한 서명
HMAC 암호화 알고리즘은 HmacSHA256 사용

AUTHPARAMS 생성하기

AUTHPARAMS 요청 예시
curl -i -X GET \
   -H "x-ncp-apigw-timestamp:1505290625682" \
   -H "x-ncp-apigw-api-key:cstWXuw4wqp1EfuqDwZeMz5fh0epaTykRRRuy5Ra" \
   -H "x-ncp-iam-access-key:D78BB444D6D3C84CA38A" \
   -H "x-ncp-apigw-signature-v1:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEo=" \
 'https://vodtranscoder.apigw.ntruss.com/api/v2/jobs?limit=10'
  • Signature 생성(개행 문자는 \n을 사용)

    요청에 맞게 StringToSign를 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다. 이 값을 x-ncp-apigw-signature-v1로 사용합니다.

  • Java 샘플 코드

public String makeSignature() {
    String space = " ";                      // one space
    String newLine = "\n";                  // new line
    String method = "GET";                  // method
    String url = "/api/v1/jobs?limit=10";    // all url except domain, include query string
    String timestamp = "{timestamp}";          // current timestamp (epoch)
    String apiKey = "{apiKey}";                // api key (from api gateway)
    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(apiKey)
        .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;
}
  • JavaScript 샘플 코드
/*
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(secretKey, method, url, timestamp, apiKey, accessKey) {
    var space = " ";
    var newLine = "\n";

    var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey);
    hmac.update(method);        // method
    hmac.update(space);            // one space
    hmac.update(url);            // url (include query string )
    hmac.update(newLine);        // new line
    hmac.update(timestamp);        // current timestamp (epoch)
    hmac.update(newLine);        // new line
    hmac.update(apiKey);        // api key (from api gateway)
    hmac.update(newLine);        // new line
    hmac.update(accessKey);        // access key (from portal or iam)

    var hash = hmac.finalize();

    return hash.toString(CryptoJS.enc.Base64);
}

VOD Transcoder API 요청 구성

Header
  x-ncp-apigw-timestamp:{Timestamp}
  x-ncp-apigw-api-key:{API Gateway API Key}
  x-ncp-iam-access-key:{Sub Account Access Key}
  x-ncp-apigw-signature-v1:{API Gateway Signature}
  Content-Type:application/json
Body
  Json Object
URL
  https://vodtranscoder.apigw.ntruss.com/api/v2/{action}

VOD Transcoder API 요청 샘플

curl -i -X POST "https://vodtranscoder.apigw.ntruss.com/api/v1/jobs" \
 -H "Content-Type:application/json" \
 -H "x-ncp-apigw-timestamp:1521787414578" \
 -H "x-ncp-apigw-api-key:AKLJsfKIy12AJDW0Q2MxANdoiAZKxWwG3NOvT6aZ" \
 -H "x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy" \
 -H "x-ncp-apigw-signature-v1:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=" \
 -d '{"jobName": "api-guide", "inputs": [{ "inputContainerName": "api-guide","inputFilePath": "/Sample.mp4"}],"output":{"outputContainerName": "api-guide","outputFilePath": "/vodtr/","thumbnailOn":"true","thumbnailContainerName": "api-guide","thumbnailFilePath":"/vodtr/","outputFiles": [{"presetId": "0dfd1eee-04c9-11e8-b51d-421453cae184","outputFileName": "720p"}]}}'

VOD Transcoder API Content-Type

VOD Transcoder API HTTP Request와 Response body를 통해 전달되는 모든 데이터의 content-type은 application/json을 사용합니다.

VOD Transcoder API 목록

VOD Transcoder API 에러 타입

VOD Transcoder API 요청이 잘못되었거나, 처리 도중 오류가 발생하면 오류 정보를 응답으로 전달합니다.

에러 타입은 VOD Transcoder API '기본 에러 타입'과 'API Gateway 에러 타입' 두 가지입니다.

기본 에러 타입

VOD Transcoder v1 API 공통 에러 코드입니다.

에러 코드 응답 메시지 설명
0 Ok
240000 Form validation failed
240001 Resource not found
240002 Access denied
240003 Server error
240004 Unauthorized
240005 Bad Request

API Gateway 에러 타입

자세한 내용은 "API Gateway 설명서(구, 사용자 가이드)"에서 확인하실 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...