如何整合

OxOffice Online 主機

儘管可以和 Web 伺服器安裝在同一主機，不過，我們建議將 OxOffice Online 安裝在專用的 VM 或伺服器。這部伺服器（WOPI 客戶端），必須能讓外部網際網路連線，而且還要能夠連線到您的 WOPI 伺服器（您的雲端應用系統）。

開出編輯 iframe 頁面的網站

我們假設您希望將編輯功能整合到現有網站中。 因此，在網站上，您需要提供一個 iframe，其中將顯示OxOffice Online 的編輯介面和文件本身。

要設定 iframe，WOPI 主機（您的雲端應用系統）需要從 WOPI 客戶端（OxOffice Online 伺服器）上定義的位置讀取 discovery XML。 位址如下：

https://<WOPI 客戶端 URL>:<port>/hosting/discovery

這會得到 discovery.xml，其中包含各種文件格式的 urlsrc。 urlsrc 為編輯文件用的 iframe 需要使用的位址。

接著您需要為欲編輯的檔案，提供一個名為 WOPISrc 的位址，WOPISrc 網址看起來如下：

https://<WOPI 主機 URL>/<...>/wopi/files/<file id>

這裡的 /wopi/ 實際上可以是任何以 wopi 開頭的字串，像是 /wopifiles/ 或 /wopi_implementation/都可以，但為了簡單起見，我們之後只會使用/wopi/。

<file id> 必須以 base64 編碼，也就是說只能有英文A-Z或a-z、數字 0-9 以及 - 和 _ 符號。

使用者驗證

為了能夠安全地存取文件，您的應用程式必須將身份驗證用的 token 傳遞給 OxOffice Online 的 access_token。對 OxOffice Online 而言，token 可以是任何隨機的數字或字串，它會在存取文件過程中（WOPI 客戶端對 WOPI 主機）當作 URL 的一部份傳遞。

唯一的要求是，對於識別使用者而言，token 必須是唯一的，不能和其他使用者重複，意即，若 WOPI 客戶端對 WOPISrc 所指定的 URL 進行存取時時，您必須檢查所傳遞的 token 是否與當初建立 iframe 所傳遞的 token 相符，否則您的應用程序應該拒絕錯誤的 token 存取檔案

目前這是唯一支援的身份驗證方式。

連接雲端硬碟

作為 WOPI 主機，您的應用程式必須為 OxOffice Online （WOPI 客戶端）實作幾個進入點，以便 OxOffice Online 下載使用者想要編輯的檔案，以及傳回更新檔案。

WOPI 客戶端（OxOffice Online）會呼叫上面所建立的 WOPISrc 來下載檔案：

GET https://<WOPI 主機 URL>/<...>/wopi/files/<file id>/contents?access_token=<token>

以及傳回更新檔案：

POST https://<WOPI 主機 URL>/<...>/wopi/files/<file id>/contents?access_token=<token>

目前，OxOffice Online 使用 4 個 WOPI 的檔案操作，分別是：CheckFileInfo、GetFile、PutFile 以及 PutRelativeFile。

您的應用程式，必須產生參照檔案及使用者的唯一 token，該 token 可以為固定或過期，只要檔案編輯期間，可供辨識即可。該 token 會透過 URL 的 access_token=<token> 傳遞，您的應用程式也可以在接收的 HTTP header 中：

Authorization: Bearer <token>

取得 OxOffice Online 傳遞的 token。

並且需支援下列 4 個功能：

1. CheckFileInfo：以下 URL 被呼叫時，至少要以 JSON 格式，傳回 BaseFileName 和 Size。

   GET https://<WOPI 主機 URL>/<...>/wopi/files/<file id>?access_token=<token>

   OxOffice Online 可用的 CheckFileInfo 屬性列表：
   

   屬性	型別 （Data type）	必要 Required	說明
   BaseFileName	string	yes	不含路徑的檔案名稱，用來顯示在使用者的編輯畫面。
   OwnerId	string	yes	識別該檔案擁有者的唯一 ID
   Size	number (int64)	yes	以 bytes 為單位的檔案大小，64 位元長整數。
   UserId	string	yes	存取該檔案的使用者 ID。
   UserFriendlyName	string	no	使用者名稱，用來顯示在使用者的編輯畫面。
   UserCanWrite	boolean	no	如果要能夠編輯，必須設為 true，預設為 false。
   PostMessageOrigin	string	no	這是告訴 OxOffice Online。 PostMessage API. 的 WOPI 主機位址。若未指定，將無法接收 OxOffice Online 傳來的狀態。
   HidePrintOption	boolean	no	隱藏 OxOffice Online 的列印按鈕。但可透過 PostMessage API 來實作 WOPI 主機自己的列印 UI。
   DisablePrint	boolean	no	禁止列印文件。此外，也會在 UI 中隱藏列印選項。
   HideSaveOption	boolean	no	隱藏 OxOffice Online 的存檔按鈕。但仍可透過 PostMessage API 觸發，這並不會影響自動存檔功能。
   HideExportOption	boolean	no	隱藏 OxOffice Online「下載為…」 按鈕及選項，但仍可透過 PostMessage API 觸發。
   DisableExport	boolean	no	禁止匯出或下載文件。此外，也會在 UI 中隱藏下載選項。
   DisableCopy	boolean	no	禁止複製內容到剪貼簿，但文件內部仍然可以複製以及貼上外部資料。
   EnableOwnerTermination	boolean	no	授予檔案擁有者可以終止其他共編者編輯的權利，意即可在共編時，將其他共編者踢出共編行列。
   LastModifiedTime	string	no	檔案最後修改時間。使用 ISO8601 格式表示之 UTC 日期時間（YYYY-MM-DDThh:mm:ss.nnnnZ）。
   UserExtraInfo	object	no	使用者延伸資訊。請參考：UserExtraInfo Details。

   UserExtraInfo Details：

   屬性	型別 （Data type）	必要 Required	說明
   avatar	string	no	使用者頭像位址。
   mail	string	no	使用者的電子郵件位址。
   ip	string	no	使用者的 IP 位址。由於 OxOffice Online 可能透過 reverse proxy 轉址，所以自行抓取的 IP 可能不正確，此種狀況下，需透過您的應用程式，將使用者 IP 置於此屬性。
   watermark	object	no	自訂編輯浮水印。請參考 Watermark Details。

   Watermark Details：

   屬性	型別 （Data type）	必要 Required	說明
   editing	boolean	no	編輯時啟用，預設為 false。
   printing	boolean	no	列印時啟用，預設為 false。
   opacity	number(double)	no	不透明度。範圍 0.01-1.00預設為 0.20。此值愈小愈透明。
   familyname	string	no	字型名稱。
   angle	number(int)	no	旋轉角度。範圍 0-360，預設為 45°
   color	string	no	CSS  #rrggbb 表示之顏色。預設 #000000
   bold	boolean	no	粗體。預設為 false。
   italic	boolean	no	斜體。預設為 false。
   outline	boolean	no	空心字。預設為 false。
   shadow	boolean	no	陰影字。預設為 false。
   text	string	no	浮水印文字，若需多行，各行需以 \n 分隔。

   
   
2. GetFile：取得欲編輯的檔案。該 URL 被呼叫時，您的應用程式必須回傳檔案，給WOPI 客戶端（OxOffice Online）。

   GET https://<WOPI 主機 URL>/<...>/wopi/files/<id>/contents?access_token=<token>

3. PutFile：更新正在編輯的檔案。該 URL 被呼叫時，您的應用程式必須接收 WOPI 客戶端（OxOffice Online）傳來的檔案。

   POST https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>

   An optional LastModifiedTime field, containing the ISO8601 round-trip time format indicating the new/updated file’s modified time in storage after successful save, can be added to the當您的應用程式成功儲存更新的檔案後，需回應 JSON response.格式內容，格式同 SeeCheckFileInfo for的 moreLastModifiedTime：
   

   details.

   {
     "LastModifiedTime": "YYYY-MM-DDThh:mm:ss.nnnnZ"
   }

4. PutRelativeFile：另存新檔或更改檔名。該 URL 被呼叫時，您的應用程式必須接收 WOPI 客戶端（OxOffice Online）傳來的檔案。
   

   POST https://<WOPI host URL>/<...>/wopi/files/<id>?access_token=<token>