Upload API

概要

Kollus HTTP アップロード Endpointは 顧客社がアップロードしたい時点にKollus Open APIの一回性アップロード URLを発給、
APIを呼び出して獲得したアップロードURLに HTTP multipart/form-data 形式でファイルをアップロードし、以降の過程（トランスコーディング）を進めさせます。

Use case scenario

1. ユーザが顧客社のWeb siteに動画ファイルをアップロードするため、特定ページをリクエストします。
2. 顧客社のアップロードページからユーザにアップロード経路をレスポンスするためKollus Apiを使ってアップロードURL生成をリクエストします。
3. アップロードURL 生成リクエストをレスポンスするためアップロード URLとアップロード ファイルキー(Upload file key), キーの満了時間などの情報を獲得します。
4. 3からレスポンスされたアップロードURL情報に基づいて顧客に見せるアップロード ページを生成します。
5. 顧客社のアップロードページでアップロードをすると、実際アップロードは顧客社のWeb siteではなく、Kollusアップロードサーバーへ直接転送することになります。

注意事項

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

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

リクエスト規格

Upload endpointの生成

• アップロード 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.jp.kollus.com/api/v1/UploadMultiParts/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc/20151204-dh6o2goz",
        “progress_url”: “http: //upload.jp.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は各1つのファイルのみ適用されます。(1つのアップロード URLで複数のファイルを転送する場合、1回目以降のアップロードは失敗します。)
• アップロードはアップロードURLの有効期限内に完了しなければなりません。有効期限の判定はアップロードが終了した時点になります。

アップロードオプション

RETURN URL

• resultはSかFで判定されます。Sはアップロード成功、Fはアップロード失敗です。
• messageはアップロード結果を説明するメッセージとなります。 (alertに表示されるメッセージと同一です。)

Sample

<form action="http: //upload.jp.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.jp.kollus.com/api/v1/UploadMultiParts/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc/20151204-dh6o2goz",
        “progress_url”: “http: //upload.jp.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