Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
개요

概要

Kollus HTTP 업로드 Endpoint는 고객사가 업로드를 원하는 시점에 Kollus Open API의 일회성 업로드 URL 발급 API를 호출하여 획득한 업로드 URL로 アップロード Endpointは 顧客社がアップロードしたい時点にKollus Open APIの一回性アップロード URLを発給、
APIを呼び出して獲得したアップロードURLに HTTP multipart/form-data
형식으로 파일을 업로드하여, 이후 과정 (트랜스코딩) 을 진행토록 합니다.形式でファイルをアップロードし、以降の過程(トランスコーディング)を進めさせます。

Use case scenario

      Image Removed

  • 사용자가 고객사의 Web 사이트에서 동영상 파일을 업로드 하기 위해 특정 페이지를 요청합니다.
  • 고객사 업로드 페이지에서 사용자에게 업로드 경로를 반환하기 위해 Kollus Api를 이용해 업로드 URL 생성을 요청합니다.
  • 업로드 URL 생성 요청에 대한 반환으로 업로드 URL과 업로드 파일키

      Image Added

    1. ユーザが顧客社のWeb siteに動画ファイルをアップロードするため、特定ページをリクエストします。
    2. 顧客社のアップロードページからユーザにアップロード経路をレスポンスするためKollus Apiを使ってアップロードURL生成をリクエストします。
    3. アップロードURL 生成リクエストをレスポンスするためアップロード URLとアップロード ファイルキー(Upload file key), 키 만료시간 정보등을 획득합니다.
    4. 3에서 반환 받은 업로드 URL 정보를 기반으로 고객에게 보여지는 업로드 페이지를 생성합니다.
    5. 고객사의 업로드 페이지에서 업로드를 하면 실제 업로드는 고객사의 웹사이트가 아닌 Kollus 업로드 서버로 직접 전송하게 됩니다.

    유의사항

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

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

    요청규격

    업로드 엔드포인트 생성 API

    일반 업로드
    1. キーの満了時間などの情報を獲得します。
    2. 3からレスポンスされたアップロードURL情報に基づいて顧客に見せるアップロード ページを生成します。
    3. 顧客社のアップロードページでアップロードをすると、実際アップロードは顧客社のWeb siteではなく、Kollusアップロードサーバーへ直接転送することになります。

    注意事項

    HTTP プロトコルを通したアップロードに対応するため、ユーザがアップロードするに必要な情報を生成するAPIを提供します。HTTP Upload APIは以下のような特徴があります。

    • 生成されたアップロードURL, アップロードファイルキーは一度使用されたら無効になります。
    • 生成されたアップロードファイルキーは指定した時間が経過すると自動で廃棄されます。

    リクエスト規格

    Upload endpointの生成

    Query Parameters

    • access_token (API 접근 토큰)
    업로드 URL 발급 요청시에는 다음과 같은 파라미터를 설정할 수 있습니다. Request는 Kollus API 정책에 따라 HTTP
    • アクセストークン)

    アップロードURLの発給をリクエストするに当たって、次のようなパラメタ-設定が可能となります。RequestはKollus APIポリシー上、HTTP(80), POST만 지원합니다.POSTのみ対応します。

    POST keyData type기본값基本値비고備考
    expire_timeinteger600 ()값의 범위는 0 値の範囲は0 < expire_time <= 21600 입니다. 빈값을 보내거나 항목 자체를 제거하면 기본 600초로 설정됩니다.になります。空白または項目を削除した場合、基本600秒に設定されます。
    category_keystring(없음無し)업로드한 파일이 속할 카테고리의 키입니다. 빈값을 보내거나 항목 자체를 제거하면 ‘없음’에 속합니다.アップロードしたファイルが指定されるカテゴリのキーになります。空白または項目を削除した場合、「無し」に設定されます。
    titlestring(없음無し)

    입력한 제목을 컨텐츠의 제목으로 강제지정합니다. 이 값을 보내지 않거나 빈 값으로 보내면 기본적으로 파일명이 제목으로 사용됩니다.入力したタイトルをコンテンツのタイトルとして強制に指定します。転送しないまたは空白の場合、ファイル名がタイトルとして設定されます。
    is_passthrough를 1로 설정시 title은 원본파일명으로 지정됩니다.passthroughを1に設定するとtitleは原本ファイル名に指定されます。

    is_encryption_uploadinteger0 (일반非暗号化)0은 일반 업로드, 1은 암호화 업로드입니다. 암호화 업로드시 파일이 암호화 되어 Kollus의 전용 플레이어로만 재생됩니다. Security-pack이 적용되지 않은 서비스 계정에서 이 값을 1로 지정하여 요청한 경우는 업로드 URL 생성이 실패합니다.0は非暗号化アップロード, 1は暗号化アップロードになります。暗号化アップロードした場合、ファイルが暗号化され、Kollus専用プレーヤーでしか再生できなくなります。暗号化アップロードが有効化されてないサービスアカウントにこの値を1に指定してリクエストした場合、アップロードURL生成に失敗します。
    is_audio_uploadinteger0 (비디오ビデオ)0은 비디오 업로드, 1은 음원 파일 업로드 입니다.0はビデオファイル、1はオーディオファイルアップロードになります。
    is_multipart_uploadinteger0 (일반非暗号化)파일의 분할 업로드를 지원하기 위한 값입니다. 추후 제공될 기능이며, 현재는 동작하지 않습니다.ファイルの分割アップロードを設定する項目になります。今後提供する予定で現在は動作しません。
    is_passthroughinteger0 (normal)1은 1=passthrough 업로드,  0은 일반 업로드 입니다., 0=normal
    profile_keystring(없음無し)is_passthrough가 1인 경우 의미가 있습니다. passthrough=1になっている条件で使用 (profile_key={계정명アカウント名}-pc-high)
    설정設定->고급기능->인코딩 프로파일에서 확인가능합니다.
    응답규격
    >詳細設定->エンコーディングプロファイル

    レスポンス規格

    JSON / UTF-8 으로 결과를 반환 합니다.8で結果をリターンします。

    (# upload_url에 사용되는 도메인 정보를 포함한 모든 정보는 Kollus 시스템 정책에 의해 변경될 수 있습니다.urlに使用されるドメイン情報を含めた全ての情報はKollusシステムポリシーにより変更される可能性があります。)

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

    JSON Structure Description

    • error : 에러코드, 0이면 정상エラーコード 正常の場合 0
    • message : 에러의 경우 상세 설명이 포함됩니다. エラーの場合、詳細内容が含まれます。
    • result : 정상인 경우 업로드 API 호출 결과를 포함 합니다. 正常の場合アップロードAPI呼出の結果が含まれます。
      • upload_url : 업로드할 URL アップロードするURL (HTTP)
      • progress_url : 업로드 진행률을 획득할 수 있는 URL アップロード進行率の獲得ができるURL (HTTP)
      • upload_file_key : 업로드 파일키アップロードファイルキー
      • will_be_expired_at : upload_file_key 만료 시간 有効期限(unix timestamp)

    파일업로드

    업로드 URL 발급요청 API를 통해 획득한 업로드 URL

    ファイルアップロード

    アップロードURL発行リクエストAPIから獲得したアップロードURL(upload_url)이 실제 파일을 전송할 업로드 서버의 주소입니다. 이 주소에 대해 HTML が、実際にファイルを転送するアップロードサーバーのアドレスになります。このアドレスにHTML multipart/form-data 형식으로 파일을 전송해야 합니다.

    유의사항

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

    dataの形式でファイルを転送します。

    注意事項

    • 転送するファイルのinput nameはupload-fileになります。
    • 各アップロードURLは各1つのファイルのみ適用されます。(1つのアップロード URLで複数のファイルを転送する場合、1回目以降のアップロードは失敗します。)
    • アップロードはアップロードURLの有効期限内に完了しなければなりません。有効期限の判定はアップロードが終了した時点になります。

    アップロードオプション

    POST keyData type기본값基本値비고備考
    return_urlstring(없음無し)return_url이 주어지면 업로드 종료 후 해당 url로 redirect 합니다. 이때, result와 message값을 추가합니다.예> urlが設定された場合アップロード終了後に指定のurlへredirectします。ここにresultとmessage値を追加します。(*Header Protocol required )
    入力値: http://www.abc.com
    例> http://foowww.abc.com/result.html?result=S&message=...
    disable_alertinteger0기본적으로는 업로드 종료시 결과 메세지를 alert로 뿌려주도록 되어 있으나, 이 기능을 사용하지 않으려면 disable_alert값을 1로 하여 전송해주십시요.基本仕様としてアップロード終了後に結果をalertで転送することになっていますが、結果転送機能を使わない場合disable_alert値を1にして転送してください。
    redirection_scopestring‘outer’

    업로드 완료 후 redirect할 domain scope를 지정합니다. 이 옵션은 다음의 값 가운데 하나를 가질 수 있습니다.

    outer → アップロード完了後redirectするdomain scopeを指定します。このオプションは次の値の中、1つを持ちます。

    • outer -> window.top.
    location을 이용합니다.

    inner → window.location 을 이용합니다.

    no → redirect 하지 않습니다.
    • locationでredirectする
    • inner -> window.locationでredirectする
    • no -> redirectしない
    acceptstringRequest Header 가운데 Accept의 값업로드 완료 후 전달받을 결과의 컨텐츠 타입을 지정합니다. 빈값으로 두면 text/html 방식으로 전달합니다. 이 경우는 returnの中のAcceptの値アップロード完了後、転送してもらう結果のコンテンツタイプを指定します。ブランクにするとtext/html方式で送ります。この場合return_url, disable_alert, redirection_scope 옵션들을 적용하여 생성된 html 페이지가 결과로 리턴됩니다. 이 값을 scopeオプションを適用して生成されたhtml ページが結果としてreturnされます。この値を ‘application/json’ 형식으로 지정하면 위 세가지 옵션은 무시되며, 결과가 JSON 형식으로 리턴됩니다.形式に指定すると、上記の3つのオプションは無視され、結果はJSON形式でReturnされます。

    RETURN URL

    • result는 S와 F 두 값을 갖습니다. S는 업로드 성공을, F는 실패를 의미합니다.
    • message는 업로드 결과를 안내하는 메세지입니다. (alert창으로 보여지는 메세지와 같습니다.resultはSかFで判定されます。Sはアップロード成功、Fはアップロード失敗です。
    • messageはアップロード結果を説明するメッセージとなります。 (alertに表示されるメッセージと同一です。)

    Sample

    Code Block
    languagejs
    themeMidnight
    <form action="http: //upload.krjp.kollus.com/20141017-y4sae7td" method="post" enctype="multipart/form-data">
         <!-- redirect scope 설정設定 -->
         <input type=”hidden” name=”redirection_scope” value=”outer” />
    
         <!-- 업로드アップロード終了後 종료시 redirect할redirectする url 설정設定 -->
         <input type=”hidden” name=”return_url” value=”http://www.lotte.com/upload_result.html” />
    
         <!-- 업로드 종료시 alert창을 띄우지 않도록 설정 アップロード終了後 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 형식)

    응답규격


    アップロード進行率

    アップロードURL生成APIの呼出で獲得した結果からprogress_urlエントリーを参照してアップロード進行率を獲得します。(JSON形式)

    レスポンス規格

    JSON / UTF-8 으로 결과를 반환 합니다.8で結果をレスポンスします。

    Sample

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

    JSON STRUCTURE DESCRIPTION

    • error : 에러코드, 0이면 정상エラーコード 正常の場合 0
    • message : 에러의 경우 상세 설명이 포함됩니다. エラーの場合、詳細内容が含まれます。
    • result : 정상인 경우 업로드 API 호출 결과를 포함 합니다. 正常の場合アップロードAPI呼出の結果が含まれます。
      • upload_url : 업로드할 URL アップロードするURL (HTTP)
      • progress_url : 업로드 진행률을 획득할 수 있는 URL アップロード進行率の獲得ができるURL (HTTP)
      • upload_file_key : 업로드 파일키アップロードファイルキー
      • will_be_expired_at : upload_file_key 만료 시간 有効期限(unix timestamp)
    에러 케이스

    エラーケース


    StatusResultCauseSolution
    400"error": "1", "message:": "failed to create upload session. invalid request"accessToken 빈값の値が空いているaccessToken을 accessTokenに query parameter를 넣어서 요청parameterを入れてリクエスト
    400"error": "1", "message:": "The Audio profile key does not exist."accessToken 등록이안되거나 정상적이지 않는값accessToken이 올바른지 등록이 되였는지 확인登録不可または正常ではない値accessTokenが正しく登録されているかを確認
    400"error": "1", "message:": "The profile key does not exist."passthrough시 해당 passthroughで該当 profile_key이 정상적으로 받지 않았을때keyが正常にレスポンスされらい

    profile_key가 body에 넣어서 요청했는지 확인keyを bodyに入れてリクエストしているかを確認

    400"error": "1", "message:": "The profile key does not match."passthrough시 해당 passthroughで該当 profile_key가 옳바르지 않을경우keyが正常ではない値해당 該当 profile_key가 올바른지 확인keyが正しいかを確認
    500{
        "error": true,
        "message": "expired time",
        "result": {
            "type": "f",
            "upload_key": "null",
        "progress": 0
        }
    }
    expire 시간이 0이거나 또는 최대시간을 초과 하였을때expire 시간을 설정을 0이상 21600이하로 설정時間が 0 または最大値を超過expire 時間設定を 1以上 21600以下に設定
    500{
        "error": true,
        "message": "bad parameters",
        "result": {
            "type": "p",
            "upload_key": "null",
            "progress": 0
        }
    }
    upload Type의 값이 올바르지 않을경우uploadType을 n 또는 f 로 원하는값을 맞춰야 함Typeの値が正常ではない

    uploadTypeを n または f で必要な値に指定する


    200<script>alert('Failed to upload.')</script>upload 실패uploadUri을 정확하게 다시 확인후 파일을업로드해야하며, form-data의 filed가 upload-file인데 정확하게 작성해서 보냈는지 확인失敗uploadUriが正しいか確認してからファイルをアップロードする、form-dataの filedが upload-fileで正しく作成しているかを確認
    
    
    샘플코드

    サンプルコード

    Upload API – ruby

    Upload API – jquery

    Upload API – php

    Upload API – java

    Easy Heading Free