資料分享

Owned by Morris Jao
Last updated: 3月 31, 2021
6 min read

分享功能簡介

OmniStor 系統所提供的分享(Share) 功能有：一般分享和群組分享。

  1. 一般分享(Public Share)：

    • 可將檔案／目錄分享給所有人，無論是否擁有 OmniStor 帳號皆可瀏覽下載。

  2. 群組分享(Group Share)：

    • 設定協同合作資料夾
      用戶可呼叫 /fsentry/setadvancedsharecode/ API將自己的目錄指定分享給特定的 OmniStor 用戶，以便啟用協同合作資料夾功能。
      這群特定的 OmniStor 用戶屬於白名單，白名單內的用戶可以新增子目錄、上傳檔案到該分享目錄，或是對該目錄下的子目錄／檔案進行新增、搬移、更名或刪除等動作；若非白名單用戶，則無任何權限。
      ※ 備份資料夾(請參閱註解)無法被設定為協同合作資料夾。
      ※ 群組分享功能目前僅支援設定目錄(Folder)為協同合作資料夾。

    • 存取協同合作資料夾
      客戶端可依照下述步驟取得協同合作資料夾的Folder ID：

      1. 收到雲端分享碼之後，可呼叫 ServicePortal 的 /sharecode/findservicegateway/ 用雲端分享碼查詢 ServiceGateway 的位址。

      2. 取得 ServiceGateway 位址後，可呼叫 ServiceGateway的 /member/acquiretoken/ 以透過使用者帳號、密碼的驗證，來取得授權金鑰(Token)，並查詢到各 Server 的位址(例如：InfoRelay 位址)，以便進行其他 API 的操作。

      3. 得到 Token 和 InfoRelay 位址之後，可呼叫 /fsentry/getinfobysharecode/ 查詢雲端分享碼所代表的協同合作資料夾 Folder ID。

    • 使用協同合作資料夾
      如欲使用協同合作資料夾功能時，其操作之客戶端應用程式(Client Application) 必須在 HTTP Header 中提供 SID 及 ProgKey (必須採用 Authorization 的方式，Authorization Header 請參見技術文件的 /member/acquiretoken/ )，當 SID 及 ProgKey 通過 OmniStor Server 的認證後，方能啟用協同合作資料夾功能。其功能如下：

      1. 協同合作資料夾與檔案目錄操作相關之 InfoRelay API 列表：

        • /folder/create/

        • /folder/move/

        • /file/move/

        • /folder/rename/

        • /folder/remove/

        • /file/remove/

        • /find/propfind/

          以上 API 皆有一個選擇性輸入參數 <isgroupaware> ( /find/propfind/ 則是參數<isshared>)，將輸入參數<isgroupaware>值(或是 /find/propfind/的<isshared>)設為 1 才會啟用協同合作資料夾功能；若不輸入該參數或值為 0，則將不會啟用協同合作資料夾功能。

          ※ 範例：
          用戶 Anson 將目錄 AlienVideo 設為協同合作資料夾並指定分享給白名單成員為 Bush、Cella。當 Bush、Cella 呼叫 /file/rename/ API，並將參數<isgroupaware>設為 1 後可將 AlienVideo 目錄下的指定檔案更名；若 Bush、Cella 未指定<isgroupaware>值為 1，則此更名動作將失敗。

      2. 協同合作資料夾上傳檔案相關之 WebRelay API 列表：

        • /webrelay/directupload/

        • /webrelay/initbinaryupload/

        • /webrelay/resumebinaryupload/

        • /webrelay/finishbinaryupload/

          亦需指定 SID／ProgKey／啟用協同合作資料夾的輸入參數，方可使用協同合作資料夾功能(詳情請參見 WebRelay 技術文件)。

      3. 長分享碼與短分享碼
        OmniStor 系統的雲端分享碼有「長分享碼」與「短分享碼」，兩者可透過呼叫 ServicePortal 的 API 進行轉換。
        OmniStor 系統為了強化資安措施，提供了長分享碼供客戶端使用，並且為了便利台灣在地化服務還提供了短分享碼可至全國 7-ELEVEN 超商 ibon 列印。呼叫 /fsentry/setadvancedsharecode/ API 可得到長分享碼，為了使用者在 ibon 手動輸入雲端分享碼方便起見，另有短分享碼與長分享碼互相轉換的。

        • /sharecode/tocompactform/：長分享碼轉換為短分享碼。

        • /sharecode/tonormalform/：短分享碼轉換為長分享

          短分享碼與長分享碼互相轉換的 API 詳情請參見 ServicePortal 技術文件。

      4. 台灣ibon列印OmniStor提供台灣在地化服務，只須攜帶短的雲端分享碼(Share Code) 便可至全國 7-ELEVEN 超商 ibon 列印(如下圖)。


        ※ ibon 列印功能目前僅支援「短分享碼」。
        ※「長分享碼」須呼叫 ServicePortal 的 /sharecode/tocompactform/ 轉換成「短分享碼」方能進行 ibon 列印。
        ※ 7-ELEVEN ibon 雲端列印相關詳請請參考 OmniStor 雲端列印。

分享檔案或目錄

  • 伺服器：InfoRelay

  • 目的：

    • 一般分享(Public Share)：
      此 API 可將用戶的檔案／目錄設定為分享檔案或分享目錄，並且取得對應的雲端分享碼(Share Code 請參閱註解)。一般分享(Public Share) 分為公開被任何客戶端存取或者密碼保護兩種方式。

    • 群組分享(Group Share)：
      此 API 亦可供用戶設定分享白名單，將自己的指定目錄分享給其他用戶。當其他用戶收到雲端分享碼後，其他用戶的客戶端應用程式或網站可呼叫 /fsentry/getinfobysharecode/ API 取得該雲端分享碼代表的 Folder ID，便可根據取得的 Folder ID 使用其它 Info Relay API 做後續的操作。

注意事項
※ 群組分享功能目前僅支援設定目錄(Folder) 為協同合作資料夾。
※ 白名單及設定協同合作資料夾的詳細說明請參照本文件「InfoRelay 分享功能簡介」。
※ 每次呼叫該 API 都會增加一個新的雲端分享碼，而舊的雲端分享碼仍保持有效。但是檔案／目錄的分享狀態(<password>、<validityduration>、<shareforuserid>、<folderquota>參數的效果)無論新舊分享碼皆採用最新一個雲端分享碼的設定

※ 範例：
有一分享目錄A，舊分享碼設定密碼為「abc123」；新分享碼設定密碼為「def456」。舊分享碼依舊可以存取到目錄 A，但存取所需的密碼已變更為「def456」。

※ 長分享碼：

  • OmniStor 系統的雲端分享碼有「長分享碼」與「短分享碼」兩種類型，此 API 取得的雲端分享碼為「長分享碼」類型。

  • 「長分享碼」須呼叫 ServicePortal 的 /sharecode/tocompactform/ 轉換成「短分享碼」方能進行 ibon 列印。

POST /fsentry/setadvancedsharecode/

Input

<!--?xml version="1.0" encoding="utf-8" ?--> <setadvancedsharecode> <token>{ token }</token> <userid>{ User ID }</userid> <isfolder>[ 0 | 1 ]</isfolder> <!-- 0：表示為 File ID | 1：表示為 Folder ID。若為 File ID，將不支援白名單功能。 --> <entryid>{ File ID | Folder ID }</entryid> <clearshare>[ 0 | 1 ]</clearshare> <!-- 選擇性欄位，預設值為 0。若設為 1 表示刪除此檔案／目錄以及子目錄下所有的雲端分享碼，不再分享此 Entry。設定此參數時，系統會忽視 isfolder、entryid 之外的參數特性(Ex: <password>、 <isgroupaware>參數) --> <clearpassword>[ 0 | 1 ]</clearpassword> <!-- 選擇性欄位，預設值為 0。若設為 1 表示移除存取此 Entry 時所需的密碼，可直接存取。設定此參數時，系統會忽視<password>參數 --> <clearvalidityduration>[ 0 | 1 ]</clearvalidityduration> <!-- 選擇性欄位，預設值為 0。若設為 1 表示移除此分享碼的時間限制。設定此參數時，系統會忽視<validityduration>參數 --> <releasequotalimit>[ 0 | 1 ]</releasequotalimit> <!-- 選擇性欄位，預設值為 0。若設為 1 表示移除此分享碼的使用空間限制。設定此參數時，系統會忽視<folderquota>參數 --> <password>{ 透過分享碼存取該檔案／目錄所須的密碼 }</password> <!-- 選擇性欄位。預設為無此欄位，表示不須密碼 --> <validityduration>{ 雲端分享碼多久後失效 }</validityduration> <!-- 選擇性欄位。單位：小時--> <isgroupaware>[ 0 | 1 ]</isgroupaware> <!-- 選擇性欄位。0：不啟用協同合作資料夾功能 | 1：啟用協同合作資料夾功能 --> <!-- shareforuserid element可以重覆多次，為選擇性欄位 --> <shareforuserid>{ 協同合作資料夾被分享者 User ID#1 }</shareforuserid> <shareforuserid>{ 協同合作資料夾被分享者 User ID#2 }</shareforuserid> <shareforuserid>{ …… }</shareforuserid> <shareforuserid>{ 協同合作資料夾被分享者 User ID#N }</shareforuserid> <folderquota>{ 設定協同合作資料夾被分享者可上傳檔案的空間上限 }</folderquota> <!-- 選擇性欄位。單位：byte --> </setadvancedsharecode>

Output

<!--?xml version="1.0" encoding="utf-8" ?--> <setadvancedsharecode> <status>{ Status Code }</status> <scrip>{ Scrip }</scrip> <sharecode>{ 雲端分享碼 }</sharecode> <ispasswordneeded>[ 0 | 1 ]</ispasswordneeded> <!-- 0：不須密碼即可存取 | 1：須輸入密碼 --> <isgroupaware>[ 0 | 1 ] </isgroupaware> <!-- 若為 1 表示支援群組編輯，反之，則不支援 --> <shareforuserid>{ 協同合作資料夾被分享者 User ID#1 }</shareforuserid> <shareforuserid>{ 協同合作資料夾被分享者 User ID#2 }</shareforuserid> <shareforuserid>{ …… }</shareforuserid> <shareforuserid>{ 協同合作資料夾被分享者 User ID#N }</shareforuserid> <expiredtime>{ yyyy-MM-dd HH:mm:ss。若此欄為空表示未指定逾期時間 }</expiredtime> <!-- 單位：小時--> <folderquota>{ 協同合作資料夾被分享者可上傳檔案的空間上限 }</folderquota> <!-- 單位：byte --> <invaliduserid>{ 不是 OmniStor 帳號的白名單用戶 }</invaliduserid> <!-- 可為多筆的。不屬於 OmniStor 帳號的用戶無法使用群組分享功能 --> </setadvancedsharecode>

回傳的狀態碼(Status Code)

狀態碼

狀態描述

狀態碼

狀態描述

0

Success。

2

Authentication Fail。

218

要處理的目錄不存在或已刪除。

219

要處理的檔案不存在或已刪除。

225

參數值不在容許的定義域內。

999

General Error。

用檔案、目錄 ID 查詢分享狀態

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端輸入檔案／目錄的 ID 以取得檔案／目錄的雲端分享碼(Share Code) 及檔案／目錄的資訊( <ispasswordneeded>、<isgroupaware>、<shareforuserid>、<expiredtime>、<folderquota>)。

此 API 取得的雲端分享碼為「長分享碼」類型。

POST /fsentry/getadvancedsharecode/

Input

<!--?xml version="1.0" encoding="utf-8" ?--> <getadvancedsharecode> <token>{ token }</token> <userid>{ User ID }</userid> <isfolder>[ 0 | 1 ] </isfolder> <!-- 0：表示為File ID | 1：表示為Folder ID --> <entryid>{ File ID | Folder ID }</entryid> </getadvancedsharecode>

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

218

要處理的目錄不存在或已刪除。

219

要處理的檔案不存在或已刪除。

225

參數值不在容許的定義域內。

999

General Error。

用雲端分享碼查詢檔案、目錄的資料

  • 伺服器：InfoRelay

  • 目的：此API可供客戶端用雲端分享碼(Share Code) 查詢所代表的檔案／目錄資料。可查詢的資料為：檔案／目錄的ID、檔案／目錄的型別(File 或是 Folder)。

此API僅支援「長分享碼」

POST /fsentry/getinfobysharecode/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

218

要處理的目錄不存在或已刪除。

225

參數值不在容許的定義域內。

243

參數值不在容許的定義域內。

999

General Error。

列出自己分享給別人的協同合作資料夾

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端輸入 User ID 及 Token 以查詢列出該 User ID 分享給其他用戶的協同合作資料夾資訊(此資訊包括：Folder ID、目錄名稱……等)。

POST /groupawareentry/listsharingtoothers/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

218

要處理的目錄不存在或已刪除。

225

參數值不在容許的定義域內。

999

General Error。

列出別人分享給自己的協同合作資料夾

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端輸入 User ID 及 Token 以查詢列出其他用戶分享給該 User ID 的協同合作資料夾資訊(此資訊包括：Folder ID、目錄名稱……等)。

POST /groupawareentry/listsharingfromothers/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

5

Developer Authentication Fail。(例如：sid 不存在或 ProgKey 驗證失敗。)

218

要處理的目錄不存在或已刪除。

225

參數值不在容許的定義域內。

999

General Error。

拒絕別人分享給我的協同合作資料夾

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端指定協同合作資料夾的 Folder ID，以取消自己在該協同合作資料夾中的白名單身分。此 API 不會影響協同合作資料夾的資料。

  • 例子：用戶 A 使用 /fsentry/setadvancedsharecode/ 指定協同合作資料夾分享給用戶 B、C、D，則白名單為 B、C、D。用戶 B 若不願看到 A 提供的協同合作資料夾，可以使用此 API 取消來自 A 的分享關係，而白名單將變更為 C、D。此 API 不會影響 A 指定的協同合作資料夾裡面的資料。

POST /groupawareentry/rejectsharing/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

218

要處理的目錄不存在或已刪除。

225

參數值不在容許的定義域內。

999

General Error。

中止分享檔案、目錄

  • 伺服器：InfoRelay

  • 目的：將用戶先前設定為分享檔案或分享目錄的分享碼(Share Code 請參閱註解)刪除，不再對外分享指定的檔案或目錄。取得分享碼(Share Code) 相關的說明可參考 API：/fsentry/setadvancedsharecode/

POST /fsentry/deletesharecode/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

999

General Error。

取得用戶分享的檔案目錄清單

  • 伺服器：InfoRelay

  • 目的：客戶端可以使用此 API 取得用戶分享的檔案或目錄清單，並且可顯示於網頁或應用程式。

POST /fsentry/getsharedentries/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

3

Payload is not validate。

999

General Error。

查詢分享檔案是否有密碼保護

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端檢驗指定之分享碼(Share Code 請參閱註解) 是否須輸入密碼才可存取。取得分享碼(Share Code) 相關的說明可參考 API：/fsentry/setadvancedsharecode/

POST /fsentry/checkpassword/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

3

Payload is not validate。

218

要處理的目錄不存在或已刪除。

219

要處理的檔案不存在或已刪除。

999

General Error。

驗證分享檔案密碼

  • 伺服器：InfoRelay

  • 目的：此 API 可供客戶端驗證分享檔案／目錄的密碼(此密碼指的是檔案／目錄被分享時所設定的存取密碼)。取得分享碼(Share Code) 相關的說明可參考 API：/fsentry/setadvancedsharecode/

POST /fsentry/comparepassword/

Input

Output

回傳的狀態碼(Status Code)

 

 

 

 

0

Success。

2

Authentication Fail。

3

Payload is not validate。

218

要處理的目錄不存在或已刪除。

219

要處理的檔案不存在或已刪除。

229

存取指定檔案的密碼不正確。

999

General Error。

其他注意事項

系統資料夾ID列表

類別

名稱

Folder ID

類別

名稱

Folder ID

system.{package}.home.root

我的收藏

0

system.backup.root

我的備份

-3

system.sync.root

同步中心

-5