# Upload API

### 1. 概要 <a href="#uploadapi-gai-yao" id="uploadapi-gai-yao"></a>

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

#### Use case scenario       <a href="#uploadapi-usecasescenario" id="uploadapi-usecasescenario"></a>

<figure><img src="https://1521757062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEecKUA6wx5AYrn8vpxDR%2Fuploads%2F1qlo3E4c7MqlmVjVd9pM%2FUpload%20API.jpeg?alt=media&#x26;token=b4cc5003-b3ab-4552-a800-032f1a4cfa74" alt=""><figcaption></figcaption></figure>

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

### 2. 注意事項 <a href="#uploadapi-zhu-yi-shi-xiang" id="uploadapi-zhu-yi-shi-xiang"></a>

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

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

### 3. リクエスト規格 <a href="#uploadapi-rikuesuto" id="uploadapi-rikuesuto"></a>

#### Upload endpointの生成API

* アップロードAPI URL :[ ](https://api.jp.kollus.com/0/media_auth/upload/create_url)[https://c-api-jp.kollus.com/api/upload/create-url](https://c-api-kr.kollus.com/api/upload/create-url)
* APIから取得したアップロード URL : <https://upload.jp.kollus.com/api/v1/create_url>&#x20;

#### Query Parameters

* access\_token ([API アクセストークン](https://catenoid-support.gitbook.io/kollus-vod-console-jp/sbisugaido/sbisunisurukkey-vod-live))

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

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

### 4. レスポンス規格 <a href="#uploadapi-resuponsu" id="uploadapi-resuponsu"></a>

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. ファイルアップロード <a href="#uploadapi-fairuappurdo" id="uploadapi-fairuappurdo"></a>

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

#### **注意事項**

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

#### **アップロードオプション**

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

#### **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)

### ６．エラーケース <a href="#uploadapi-erksu" id="uploadapi-erksu"></a>

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

### **サービスサポート**

> サンプルコードについてのお問い合わせは担当までご連絡ください。
>
> E-mail お問い合わせ > <jp_team@catenoid.net>
>
> 電話番号 > 03-4405-8462