OmniStor API


OmniStor API 概述

OmniStor 除了提供檔案基本操作的 API 外,還包括取得相片的縮圖、影片的截圖、以及萃取文件內容等功能;以通用的 HTTPS 協定進行資料傳輸,提供高度互通性,並廣泛支援多種開發環境,且透過 SSL 2048bit 加密增加資料安全性。 您須遵循一致的原則使用 OmniStor API 來存取資料:

  • 取得授權
    通過嚴謹、安全的帳號驗證程序取得授權 Token,並在每一次 API 使用時帶入 Token。

  • 瀏覽或操作檔案及目錄
    透過HTTPS通用協定可輕易操作檔案及目錄等資源。


各伺服器簡介

ServiceGateway功能簡介

ServiceGateway主要功能在於調度一個 Service Area 內實際提供服務的主機,針對該 Service Area(請參閱本文下方「服務區域ID列表」)內的使用者,ServiceGateway 會分配一組適合的相關伺服器位址。

ServiceGateway中用來授權驗證(Acquire Token)使用者的API是 /member/acquiretoken/,該 API 會回傳 Token、InfoRelay 以及 WebRelay 的位址給客戶端。接著,客戶端便可以帶著 ServiceGateway 所核發的 Token 自由使用 InfoRelay 和 WebRelay 提供的API開發 OmniStor 的相關服務。

OmniStor 用戶遍佈全球,著眼於各 Service Area 內某特定之服務的使用期限,帳號可以分為數種狀態:NORMAL State、COUNTING DOWN State、FROZEN State及CLOSE State。

帳戶使用期限狀態的定義

  • NORMAL State
    為 OmniStor 的正常狀態,檔案上傳下載及系統相關功能皆可正常使用。用戶可按照購買系統使用權時之契約執行所有功能。

  • COUNTING DOWN State
    距離使用期限少於指定的時間長度(目前訂為15天)之即將到期狀態。

  • FROZEN State
    該狀態是指用戶已屆使用期限,未再購買使用時數。FROZEN 狀態最長維持1個月,此段期間內用戶的資料仍被保存於系統內。在此狀態中,用戶無法上傳檔案。

  • CLOSE State用戶在 FROZEN 狀態超過 1個月仍未購買使用時數,則該用戶之帳號將被關閉。於此狀態下,Acquire Token 雖可取得有效的 Token,但用戶檔案及其目錄將被清除,亦無建立目錄或上傳檔案的功能,讓用戶可接受系統的提示購買訊息。此時,可透過購買使用時數回到 NORMAL 狀態。

Auxiliary Password(CAPTCHA)機制

CAPTCHA

用戶登入 OmniStor 系統輸入之帳號(User ID)或密碼(Passowrd)組合若不相符且超過系統設定的容許錯誤次數,則系統會自動增加另一個圖型驗證碼傳送給客戶端,用戶必須輸入正確的 User ID / Password / CAPTCHA 字串才可以通過身份驗證,此機制可以預防存心不良的客戶端以 ROBOT 用各種帳號密碼組合不斷嘗試自動登入系統,藉此提高系統安全性。


ServiceGateway API 簡介

客戶端在使用 OmniStor 時須經過幾個步驟:

  1. 首先,客戶端必須先向 ServicePortal 取得本身所屬之 Service Area 的 ServiceGateway 位址。
    註:透過呼叫 ServicePortal 的 /member/requestservicegateway/ 可以達成這個目的。

  2. 接著,客戶端需要帶著使用者的帳號(User ID)和密碼(Password),透過 ServicePortal 取得的 ServiceGateway 位址進行 /member/acquiretoken/ 呼叫。
    2-1. 將客戶端傳來的使用者帳號密碼進行認證。
    2-2. 若帳號密碼無誤,則 ServiceGateway 核發的 Token 將伴隨著 InfoRelay、WebRelay 的位址回傳給客戶端。

為減少對 ServicePortal 的存取,客戶端可以在首度取得 ServiceGateway 位址後便儲存在本地電腦,直到發生客戶端無法連上先前儲存的 ServiceGateway 時再重新向 ServiceGateway 詢問所在地的 Service Area 內的 Service Gateway 位址。

API 共通 Header

當客戶端呼叫 API 時,Cookie 必須指定 sid 欄位值供 ServiceGateway 記錄客戶端的資訊,Cookie 中的「sid」須為小寫英文字母。


InfoRelay功能簡介

凡是不直接更動檔案本身的各種操作皆由 InfoRelay 負責處理。例如:瀏覽目錄內容、檢視目錄的分享清單及搬移目錄……等。

InfoRelay API使用前說明

客戶端程式在實際呼叫 InfoRelay 的 API 之前,必須先向 ServcieGateway 取得 Token:

  1. 首先,客戶端必須先向 ServicePortal 取得 ServiceGateway 位址。伴隨客戶端所屬的 Service Area (請參閱本文下方的「服務區域ID列表」)不同,所取得的 ServiceGateway 位址也將不同。
    註:透過呼叫 ServicePortal 的 /member/requestservicegateway/ 可以達成這個目的。

  2. 取得 ServiceGateway 位址之後,客戶端需要呼叫 /member/acquiretoken/

    1. 客戶端發送使用者的帳號(User ID) 和密碼(Password) 至 ServiceGateway 進行認證。

    2. 若帳號密碼無誤,則 ServiceGateway 將回傳 Token 以及 InfoRelay/ WebRelay 的位址給客戶端。

完成一次上述流程之後,客戶端方能帶著 ServiceGateway 核發的 Token 使用 InfoRelay/WebRelay 提供的API。直到 Token 失效,才必須再次呼叫 /member/acquiretoken/ 取得新的Token。

API 共通 Header

當客戶端呼叫 API 時,Cookie 必須指定 sid 欄位值供 ServiceGateway 記錄客戶端的資訊,Cookie 中的 sid 須為小寫英文字母。


WebRelay 功能簡介

WebRelay 的功能主要是提供客戶端在 OmniStor 系統中進行實體檔案的存取動作,並支援網路瀏覽器(Web Browser) 的執行。例如:檔案上傳、檔案下載、影片格式轉換和取得圖片檔的縮圖…等。

WebRelay API 簡介

若客戶端程式欲呼叫使用 WebRelay 的 API,則必須先向 ServiceGateway 取得 Token 及 WebRelay 的位址,步驟如下:

  1. 首先,客戶端必須先向 ServicePortal 取得本身所屬之 Service Area(請參閱本文下方的「服務區域 ID 列表」)的 ServiceGateway 位址。
    註:透過呼叫 ServicePortal 的 /member/requestservicegateway/ 可以達成這個目的。

  2. 接著,客戶端需要帶著使用者的帳號(User ID) 和密碼(Password),向 ServiceGateway 呼叫 /member/acquiretoken/ 以取得Token。

    1. 將客戶端傳來的使用者帳號和密碼進行認證。

    2. 若帳號密碼無誤,則 ServiceGateway 將會核發 Token,並且將 InfoRelay / WebRelay 的位址回傳給客戶端。取得 WebRelay 的位址之後,客戶端便可以開始呼叫使用 WebRelay 的 API。

完成一次上述流程之後,客戶端方能帶著 ServiceGateway 核發的 Token 使用 InfoRelay/WebRelay 提供的 API。直到Token 失效,才必須再次呼叫 /member/acquiretoken/ 取得新的 Token。


Search Server API 簡介

為確保網路安全性,所有 API 採 HTTPS 傳輸,而且客戶端須向 ServiceGateway 傳送 Token 以進行驗證。而 Token 的傳遞是以 URL Rewriting 的方式附加於 API 的路徑之後。以 /fulltext/sqlquery/ 為例,客戶端向 Search Server 傳遞的 URL 為:http://{ search server IP }/fulltext/sqlquery/{ token }

API 共通 Header

當客戶端呼叫 Search Server API 時,Cookie 必須指定 sid 欄位值供 Search Server 記錄客戶端的資訊,Cookie 中的 sid 須為小寫英文字母。


服務區域 ID 列表

服務區域ID

服務區域

服務區域ID

服務區域

1

台灣、日本、韓國,及東南亞地區

2

美洲、澳洲

3

中國大陸

5

歐洲、非洲,及中東地區