如何整合

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 僅使用 3 個 WOPI 檔案操作（GetFile／PutFile／CheckFileInfo）。

你的應用程式，至少具備以下 5 個功能：

能夠產生參照檔案及使用者的唯一 token，該 token 可以為固定或過期，只要檔案編輯期間，可供辨識即可。
CheckFileInfo：以下 URL 被呼叫時，至少要以 JSON 格式，傳回 BaseFileName 和 Size。
```
GET https://<WOPI 主機 URL>/<...>/wopi/files/<file id>?access_token=<token>
```
以下是 OxOffice Online 必要的 CheckFileInfo 屬性：

BaseFileName – 不含路徑的檔案名稱，用來顯示在使用者的編輯畫面。

OwnerId – 識別該檔案擁有者的唯一 ID（字串）。

Size – 以 bytes 為單位的檔案大小，64 位元長整數。

UserId – 存取該檔案的使用者 ID（字串）。

Collabora Online takes the following optional CheckFileInfo properties:
- UserFriendlyName – The name of the user, suitable for displaying on the UI.
- UserCanWrite – It has to be set to true if the file is opened for editing.
- PostMessageOrigin – It is used by PostMessage API.
- HidePrintOption – Hides print button from UI but accessible using PostMessage API so hosts can implement their own UI for this.
- DisablePrint – Disables printing of documents. Additionally, hides print option from UI.
- HideSaveOption – Hides save button from UI. Manual save can still triggered using PostMessage API. Does not affect automatic save.
- HideExportOption – Hides ‘Download as’ button/menubar item from UI. Can still be triggered using PostMessage API.
- DisableExport – Disable export of the document in any format. Additionally, hides the ‘Download as’ button from the UI.
- DisableCopy – Disable copying from the document.
- EnableOwnerTermination – This gives document owners the ability to terminate all sessions currently having that document opened.
- LastModifiedTime – ISO8601 round-trip time format for file’s last modified time in storage.
- IsUserLocked – Lock the user from using certain feature(s) which can be later be unlock by user.
- IsUserRestricted – Disable feature(s) for the user.

GetFile：取得欲編輯的檔案，您的應用程式必須回傳檔案。

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

PutFile：更新正在編輯的檔案。

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

PutRelativeFile：