Upload API

개요

Kollus HTTP 업로드 Endpoint는 고객사가 업로드를 원하는 시점에 Kollus Open API의 일회성 업로드 URL 발급 API를 호출하여 획득한 업로드 URL로 HTTP multipart/form-data 형식으로 파일을 업로드하여, 이후 과정 (트랜스코딩) 을 진행토록 합니다.

Use case scenario

1. 사용자가 고객사의 Web 사이트에서 동영상 파일을 업로드 하기 위해 특정 페이지를 요청합니다.
2. 고객사 업로드 페이지에서 사용자에게 업로드 경로를 반환하기 위해 Kollus Api를 이용해 업로드 URL 생성을 요청합니다.
3. 업로드 URL 생성 요청에 대한 반환으로 업로드 URL과 업로드 파일키(Upload file key), 키 만료시간 정보등을 획득합니다.
4. 3에서 반환 받은 업로드 URL 정보를 기반으로 고객에게 보여지는 업로드 페이지를 생성합니다.
5. 고객사의 업로드 페이지에서 업로드를 하면 실제 업로드는 고객사의 웹사이트가 아닌 Kollus 업로드 서버로 직접 전송하게 됩니다.

유의사항

HTTP 프로토콜을 이용한 업로드를 지원하기 위해 사용자에게 업로드에 필요한 정보를 생성하는 API를 제공합니다. HTTP Upload API는 아래와 같은 특성을 갖습니다.

• 생성된 업로드 URL, 업로드 파일키는 일회용입니다.
• 생성된 업로드 파일키는 지정된 시간 이후 자동 폐기됩니다.

요청규격

업로드 엔드포인트 생성 API

• 일반 업로드 URL : http://api.kr.kollus.com/0/media_auth/upload/create_url
• 패스쓰루 업로드 URL : http://upload.kr.kollus.com/api/v1/create_url

Query Parameters

• access_token (API 접근 토큰)

업로드 URL 발급 요청시에는 다음과 같은 파라미터를 설정할 수 있습니다. Request는 Kollus API 정책에 따라 HTTP(80), POST만 지원합니다.

응답규격

JSON / UTF-8 으로 결과를 반환 합니다.

(# upload_url에 사용되는 도메인 정보를 포함한 모든 정보는 Kollus 시스템 정책에 의해 변경될 수 있습니다.)

Sample
{
    "error": 0,
    "message": "",
    "result": {
        "upload_url": "http: //upload.kr.kollus.com/api/v1/UploadMultiParts/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc/20151204-dh6o2goz",
        “progress_url”: “http: //upload.kr.kollus.com/api/v1/GetUploadingProgress/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc”,
        "upload_file_key": "20141017-y4sae7td",
        "will_be_expired_at": 1413883670
    }
}

JSON Structure Description

• error : 에러코드, 0이면 정상
• message : 에러의 경우 상세 설명이 포함됩니다.
• result : 정상인 경우 업로드 API 호출 결과를 포함 합니다.
  • upload_url : 업로드할 URL (HTTP)
  • progress_url : 업로드 진행률을 획득할 수 있는 URL (HTTP)
  • upload_file_key : 업로드 파일키
  • will_be_expired_at : upload_file_key 만료 시간 (unix timestamp)

파일업로드

업로드 URL 발급요청 API를 통해 획득한 업로드 URL(upload_url)이 실제 파일을 전송할 업로드 서버의 주소입니다. 이 주소에 대해 HTML multipart/form-data 형식으로 파일을 전송해야 합니다.

유의사항

• 전송할 파일의 input name은 upload-file입니다.
• 하나의 업로드 URL은 하나의 파일에 대응합니다. (하나의 업로드 URL로 하나 이상의 파일을 전송하려 시도할 경우 뒤에 업로드하는 파일의 업로드는 실패합니다.)
• 업로드는 업로드 URL의 만료시간 전까지 완료되어야 합니다. 만료시간 판단은 업로드 시작 시점이 아니라 종료 시점에 판단합니다.

업로드 옵션

RETURN URL

• result는 S와 F 두 값을 갖습니다. S는 업로드 성공을, F는 실패를 의미합니다.
• message는 업로드 결과를 안내하는 메세지입니다. (alert창으로 보여지는 메세지와 같습니다.)

Sample

<form action="http: //upload.kr.kollus.com/20141017-y4sae7td" method="post" enctype="multipart/form-data">
     <!-- redirect scope 설정 -->
     <input type=”hidden” name=”redirection_scope” value=”outer” />

     <!-- 업로드 종료시 redirect할 url 설정 -->
     <input type=”hidden” name=”return_url” value=”http://www.lotte.com/upload_result.html” />

     <!-- 업로드 종료시 alert창을 띄우지 않도록 설정 (1) -->
     <input type=”hidden” name=”disable_alert” value=”1” />

     <input type=”file” name=”upload-file” />
     <input type=”submit” />
</form>

업로드 진행률

업로드 URL 생성 API 호출을 통해 획득한 결과 가운데 progress_url 엔트리를 참조하여 업로드 진행률을 획득합니다. (JSON 형식)

응답규격

JSON / UTF-8 으로 결과를 반환 합니다.

Sample

{
    "error": 0,
    "message": "",
    "result": {
        "upload_url": "http: //upload.kr.kollus.com/api/v1/UploadMultiParts/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc/20151204-dh6o2goz",
        “progress_url”: “http: //upload.kr.kollus.com/api/v1/GetUploadingProgress/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc”,
        "upload_file_key": "20141017-y4sae7td",
        "will_be_expired_at": 1413883670
    }
}

JSON STRUCTURE DESCRIPTION

• error : 에러코드, 0이면 정상
• message : 에러의 경우 상세 설명이 포함됩니다.
• result : 정상인 경우 업로드 API 호출 결과를 포함 합니다.
  • upload_url : 업로드할 URL (HTTP)
  • progress_url : 업로드 진행률을 획득할 수 있는 URL (HTTP)
  • upload_file_key : 업로드 파일키
  • will_be_expired_at : upload_file_key 만료 시간 (unix timestamp)

에러 케이스

샘플코드

Upload API – ruby

Upload API – jquery

Upload API – php

Upload API – java