Upload API

1. 概要

Kollus HTTPアップロードエンドポイントは、顧客がアップロードしたい時点でKollus Open APIの一時的なアップロードURL発行APIを呼び出して取得したアップロードURLに、HTTPのmultipart/form-data形式でファイルをアップロードし、その後の処理（トランスコーディング）を行うようにします。

Use case scenario

• ユーザが顧客社のWeb siteに動画ファイルをアップロードするため、特定ページをリクエストします。

• 顧客社のアップロードページからユーザにアップロード経路をレスポンスするためKollus Apiを使ってアップロードURL生成をリクエストします。

• アップロードURL 生成リクエストをレスポンスするためアップロード URLとアップロード ファイルキー(Upload file key), キーの満了時間などの情報を獲得します。

• 3からレスポンスされたアップロードURL情報に基づいて顧客に見せるアップロード ページを生成します。

• 顧客社のアップロードページでアップロードをすると、実際アップロードは顧客社のWeb siteではなく、Kollusアップロードサーバーへ直接転送することになります。

2. 注意事項

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

• 生成されたアップロードURL, アップロードファイルキーは一度使用されたら無効になります。

• 生成されたアップロードファイルキーは指定した時間が経過すると自動で廃棄されます。

3. リクエスト規格

Upload endpointの生成API

• アップロードAPI URL : https://c-api-jp.kollus.com/api/upload/create-url

• APIから取得したアップロード URL : https://upload.jp.kollus.com/api/v1/create_url

Query Parameters

• access_token (API アクセストークン)

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

POST key	Data type	基本値	備考
expire_time	integer	600 (秒)	値の範囲は0 < expire_time <= 21600 になります。空白または項目を削除した場合、基本600秒に設定されます。
category_key	string	(無し)	アップロードしたファイルが指定されるカテゴリのキーになります。空白または項目を削除した場合、「無し」に設定されます。
title	string	(無し)	入力したタイトルをコンテンツのタイトルとして強制に指定します。転送しないまたは空白の場合、ファイル名がタイトルとして設定されます。 is_passthroughを1に設定するとtitleは原本ファイル名に指定されます。
is_encryption_upload	integer	0 (非暗号化)	0は非暗号化アップロード, 1は暗号化アップロードになります。暗号化アップロードした場合、ファイルが暗号化され、Kollus専用プレーヤーでしか再生できなくなります。暗号化アップロードが有効化されてないサービスアカウントにこの値を1に指定してリクエストした場合、アップロードURL生成に失敗します。
is_audio_upload	integer	0 (ビデオ)	0はビデオファイル、1はオーディオファイルアップロードになります。
is_multipart_upload	integer	0 (非暗号化)	ファイルの分割アップロードを設定する項目になります。今後提供する予定で現在は動作しません。
is_passthrough	integer	0 (normal)	1=passthrough, 0=normal
profile_key	string	(無し)	is_passthrough=1になっている条件で使用 (profile_key={アカウント名}-pc-high) 設定->詳細設定->エンコーディングプロファイル
selected_profile_key	string	(無し)	疑似ライブアップロードのみ使用します。値：(アカウントキー) Kollus Liveの疑似ライブが有効化ステータスの有効です。

4. レスポンス規格

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)

5. ファイルアップロード

アップロードURL発行リクエストAPIから獲得したアップロードURL(upload_url)が、実際にファイルを転送するアップロードサーバーのアドレスになります。このアドレスにHTML multipart/form-dataの形式でファイルを転送します。

注意事項

• 転送するファイルのinput nameはupload-fileになります。

• 各アップロードURLは各1つのファイルのみ適用されます。(1つのアップロード URLで複数のファイルを転送する場合、1回目以降のアップロードは失敗します。)

• アップロードはアップロードURLの有効期限内に完了しなければなりません。有効期限の判定はアップロードが終了した時点になります。

アップロードオプション

POST key	Data type	基本値	備考
return_url	string	(無し)	return_urlが設定された場合アップロード終了後に指定のurlへredirectします。ここにresultとmessage値を追加します。(*Header Protocol required ) 入力値: http://www.abc.com 例> http://www.abc.com?result=S&message=...
disable_alert	integer	0	基本仕様としてアップロード終了後に結果をalertで転送することになっていますが、結果転送機能を使わない場合disable_alert値を1にして転送してください。
redirection_scope	string	‘outer’	アップロード完了後redirectするdomain scopeを指定します。このオプションは次の値の中、1つを持ちます。 outer -> window.top.locationを利用します。 inner -> window.locationを利用します。 no -> redirectしない
accept	string	Request Header の中のAcceptの値	アップロード完了後、転送してもらう結果のコンテンツタイプを指定します。ブランクにするとtext/html方式で送ります。この場合return_url, disable_alert, redirection_scopeオプションを適用して生成されたhtml ページが結果としてreturnされます。この値を ‘application/json’ 形式に指定すると、上記の3つのオプションは無視され、結果はJSON形式でReturnされます。

RETURN URL

• resultはSかFで判定されます。Sはアップロード成功、Fはアップロード失敗です。

• messageはアップロード結果を説明するメッセージとなります。 (alertに表示されるメッセージと同一です。)

Sample

<form action="https://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.foobar.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形式)

レスポンス規格

application/JSON ; UTF-8で結果をレスポンスします。

Sample

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

応答結果説明

• 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)

６．エラーケース

Status	Result	Cause	Solution
400	"error": "1", "message:": "failed to create upload session. invalid request"	accessToken の値が空いている	accessTokenに query parameterを入れてリクエスト
400	"error": "1", "message:": "The Audio profile key does not exist."	accessToken 登録不可または正常ではない値	accessTokenが正しく登録されているかを確認
400	"error": "1", "message:": "The profile key does not exist."	passthroughで該当 profile_keyが正常にレスポンスされらい	profile_keyを bodyに入れてリクエストしているかを確認
400	"error": "1", "message:": "The profile key does not match."	passthroughで該当 profile_keyが正常ではない値	該当 profile_keyが正しいかを確認
500	{ "error": true, "message": "expired time", "result": { "type": "f", "upload_key": "null", "progress": 0 } }	expire 時間が 0 または最大値を超過	expire 時間設定を 1以上 21600以下に設定
500	{ "error": true, "message": "bad parameters", "result": { "type": "p", "upload_key": "null", "progress": 0 } }	upload Typeの値が正常ではない	uploadTypeを n または f で必要な値に指定する
200	<script>alert('Failed to upload.')</script>	upload 失敗	uploadUriが正しいか確認してからファイルをアップロードする、form-dataの filedが upload-fileで正しく作成しているかを確認

サービスサポート

サンプルコードについてのお問い合わせは担当までご連絡ください。

E-mail お問い合わせ > [e-mail]

電話番号 > 03-4405-8462