Upload API
概要
Kollus HTTP アップロード Endpointは 顧客社がアップロードしたい時点に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アップロードサーバーへ直接転送することになります。
注意事項
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のみ対応します。
POST key | Data type | 基本値 | 備考 |
|---|---|---|---|
expire_time | integer | 600 (秒) | 値の範囲は0 < expire_time <= 21600 になります。空白または項目を削除した場合、基本600秒に設定されます。 |
category_key | string | (無し) | アップロードしたファイルが指定されるカテゴリのキーになります。空白または項目を削除した場合、「無し」に設定されます。 |
title | string | (無し) | 入力したタイトルをコンテンツのタイトルとして強制に指定します。転送しないまたは空白の場合、ファイル名がタイトルとして設定されます。 |
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) |
レスポンス規格
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の有効期限内に完了しなければなりません。有効期限の判定はアップロードが終了した時点になります。
アップロードオプション
POST key | Data type | 基本値 | 備考 |
|---|---|---|---|
return_url | string | (無し) | return_urlが設定された場合アップロード終了後に指定のurlへredirectします。ここにresultとmessage値を追加します。(*Header Protocol required ) |
disable_alert | integer | 0 | 基本仕様としてアップロード終了後に結果をalertで転送することになっていますが、結果転送機能を使わない場合disable_alert値を1にして転送してください。 |
redirection_scope | string | ‘outer’ | アップロード完了後redirectするdomain scopeを指定します。このオプションは次の値の中、1つを持ちます。
|
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="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)
エラーケース
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 | { | expire 時間が 0 または最大値を超過 | expire 時間設定を 1以上 21600以下に設定 |
500 | { | upload Typeの値が正常ではない | uploadTypeを n または f で必要な値に指定する |
200 | <script>alert('Failed to upload.')</script> | upload 失敗 | uploadUriが正しいか確認してからファイルをアップロードする、form-dataの filedが upload-fileで正しく作成しているかを確認 |
サンプルコード
Copyright © CATENOID, lnc. All Rights Reserved.
E-mail. jp_sales@catenoid.net | Tel. 03-4405-8462