Skip to main content

如何整合

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 可以為固定或過期，只要檔案編輯期間，可供辨識即可。並且需支援下列 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 It is used by PostMessage API.
    HidePrintOption boolean no Hides print button from UI but accessible using PostMessage API so hosts can implement their own UI for this.
    DisablePrint boolean no 禁止列印文件。此外，也會在 UI 中隱藏列印選項。
    HideSaveOption boolean no Hides save button from UI. Manual save can still triggered using PostMessage API. Does not affect automatic save.
    HideExportOption boolean no Hides ‘Download as’ button/menubar item from UI. Can still be triggered using PostMessage API.
    DisableExport boolean no 禁止匯出或下載文件。此外，也會在 UI 中隱藏下載選項。
    DisableCopy boolean no 禁止複製內容到剪貼簿，但文件內部仍然可以複製以及貼上外部資料。
    EnableOwnerTermination boolean no This gives document owners the ability to terminate all sessions currently having that document opened.
    LastModifiedTime
    		no ISO8601 round-trip time format for file’s last modified time in storage.
    UserExtraInfo object no 使用者延伸資訊。請參考：UserExtraInfo Object Details。
    UserExtraInfo Details：
    屬性

    型別

    （Data type）

    必要

    Required

    		 說明

    avatar

    string

    no

    		 使用者頭像位址。

    mail

    string

    no

    		 使用者的電子郵件位址。
    IPip

    string

    no

    		 使用者的 IP 位址。由於 OxOffice Online 可能透過 reverse proxy 轉址，所以自行抓取的 IP 可能不正確，此種狀況下，需透過您的應用程式，將使用者 IP 置於此屬性。
    Watermarkwatermark

    object

    no

    		 自訂編輯浮水印。請參考 Watermark Details。
    Watermark Details：
    屬性

    型別

    （Data type）

    必要

    Required

    		說明
    editingbooleanno編輯時啟用，預設為 false。
    printingbooleanno列印時啟用，預設為 false。
    opacitynumber(double)no不透明度，預設為 0.2。此值愈小愈透明。
    familynamestringno字型名稱。
    anglenumber(int)no旋轉角度，預設為 45°
    colorstringno

    CSS  #rrggbb 表示之顏色。預設 #000000

    boldbooleanno

    粗體。預設為 false。

    italicbooleanno

    斜體。預設為 false。

    outlinebooleanno

    空心字。預設為 false。

    shadowbooleanno

    陰影字。預設為 false。

    textstringno

    浮水印文字，若需多行，各行需以 \n 分隔。

  2. GetFile：取得欲編輯的檔案，您的應用程式必須回傳檔案，給WOPI 客戶端（OxOffice Online）。 
    GET https://<WOPI 主機 URL>/<...>/wopi/files/<id>/contents?access_token=<token>
  3. PutFile：更新正在編輯的檔案，您的應用程式必須接收 WOPI 客戶端（OxOffice Online）傳來的檔案。 
    POST https://<WOPI host URL>/<...>/wopi/files/<id>/contents?access_token=<token>
  4. PutRelativeFile：
Back to top