資料分享

分享功能簡介

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

一般分享(Public Share)：
- 可將檔案／目錄分享給所有人，無論是否擁有 OmniStor 帳號皆可瀏覽下載。
群組分享(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

1 分享功能簡介
2 分享檔案或目錄
- 2.1 POST /fsentry/setadvancedsharecode/
  - 2.1.1 Input
  - 2.1.2 Output
  - 2.1.3 回傳的狀態碼(Status Code)
3 用檔案、目錄 ID 查詢分享狀態
- 3.1 POST /fsentry/getadvancedsharecode/
  - 3.1.1 Input
  - 3.1.2 Output
  - 3.1.3 回傳的狀態碼(Status Code)
4 用雲端分享碼查詢檔案、目錄的資料
- 4.1 POST /fsentry/getinfobysharecode/
  - 4.1.1 Input
  - 4.1.2 Output
  - 4.1.3 回傳的狀態碼(Status Code)
5 列出自己分享給別人的協同合作資料夾
- 5.1 POST /groupawareentry/listsharingtoothers/
  - 5.1.1 Input
  - 5.1.2 Output
  - 5.1.3 回傳的狀態碼(Status Code)
6 列出別人分享給自己的協同合作資料夾
- 6.1 POST /groupawareentry/listsharingfromothers/
  - 6.1.1 Input
  - 6.1.2 Output
  - 6.1.3 回傳的狀態碼(Status Code)
7 拒絕別人分享給我的協同合作資料夾
- 7.1 POST /groupawareentry/rejectsharing/
  - 7.1.1 Input
  - 7.1.2 Output
  - 7.1.3 回傳的狀態碼(Status Code)
8 中止分享檔案、目錄
- 8.1 POST /fsentry/deletesharecode/
  - 8.1.1 Input
  - 8.1.2 Output
  - 8.1.3 回傳的狀態碼(Status Code)
9 取得用戶分享的檔案目錄清單
- 9.1 POST /fsentry/getsharedentries/
  - 9.1.1 Input
  - 9.1.2 Output
  - 9.1.3 回傳的狀態碼(Status Code)
10 查詢分享檔案是否有密碼保護
- 10.1 POST /fsentry/checkpassword/
  - 10.1.1 Input
  - 10.1.2 Output
  - 10.1.3 回傳的狀態碼(Status Code)
11 驗證分享檔案密碼
- 11.1 POST /fsentry/comparepassword/
  - 11.1.1 Input
  - 11.1.2 Output
  - 11.1.3 回傳的狀態碼(Status Code)
12 其他注意事項
- 12.1 屬性(Attribute)
- 12.2 合法的標示代碼(Mark ID)
- 12.3 MD5 編碼注意事項
- 12.4 系統資料夾ID列表