如何采用WOPI协议将Office整合到自己项目中

WOPI是一个RESTful API协议，用于整合在线办公套件和各种云应用程序。阅读这篇文章了解如何进行这种集成。

ONLYOFFICE

8805人浏览 · 2022-03-22 12:00:00

ONLYOFFICE · 2022-03-22 12:00:00 发布

WOPI（网络应用开放平台接口）是一个RESTful API协议，最早由微软发布。现在广泛用于整合在线办公套件和各种云应用程序。

在这篇文章中，我们来解释如何在ONLYOFFICE编辑器启用WOPI并将其集成到自己的项目。

如何在ONLYOFFICE Docs启用WOPI

此前，只有通过自身的API，才能将ONLYOFFICE Docs集成到 sync&share解决方案、DMS、CMS和其他云平台。从6.4.0版本开始，该套件也支持WOPI。

在ONLYOFFICE Docs中，WOPI默认情况下是非激活的。要启用WOPI，请在以下路径找到（或创建）文档服务器的配置文件： /etc/onlyoffice/documentserver/local.json，并设置wopi.enable参数为true。

{
  "wopi": {
    "enable": true
    }
}

ONLYOFFICE Docs只能处理从受信任的集成商那里收到的WOPI请求。WOPI域允许列表必须包括这种集成商的IP地址。在这一点上，必须拒绝所有其他集成商的访问。默认情况下，所有的IP地址都算是受信任的，所以您需要配置文档服务器IP过滤器。

用任何文本编辑器打开/etc/onlyoffice/documentserver/local.json文件，来改变默认设置：

"ipfilter": {
    "rules": [
    {
        "address": "ip_address",
        "allowed": true
    },
    {
        "address": "*",
        "allowed": false
    }
    ],
    "useforrequest": true,
    "errorcode": 403
}

输入您的ip_address，可以包含：

适用于ipv4，X.X.X.X格式的IP,
适用于ipv6，xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx.xxxx 格式的IP,
dns名称,
*通配符，以取代任何符号。

改变allowed参数，可以是true或false。然后，重新启动服务以使配置的改变生效:

supervisorctl restart all

WOPI操作基础知识

WOPI定义一组方法和操作，允许在文档存储和在线编辑器之间进行交互。WOPI规范遵循一定的术语。

WOPI服务器（host）：实现REST API的文件管理系统。
WOPI客户端（client）： 在线编辑器，在本文中我们以ONLYOFFICE Docs为例。
WOPI发现（dicovery)：http(s)://<online-editor-address>/hosting/discovery

在Node.js测试应用程序页面上有一个初始化编辑器的discovery数据请求的例子。discovery请求的响应以XML格式返回，并包含关于ONLYOFFICE编辑器、支持的格式和操作（例如，查看、编辑、编辑新内容等）的信息。

ONLYOFFICE Docs的discovery回应实例：

<wopi-discovery>
 <net-zone name="external-http">
  <app name="Word" favIconUrl="https://<editor_address>/webapps/apps/documenteditor/main/resources/img/favicon.ico">
  <action name="edit" ext="docx" default="true" requires="locks,update" urlsrc="https://<editor_address>/hosting/wopi?documentType=word&mode=edit&<rs=DC_LLCC&><dchat=DISABLE_CHAT&><e=EMBEDDED&><fs=FULLSCREEN&><hid=HOST_SESSION_ID&><rec=RECORDING&><sc=SESSION_CONTEXT&><thm=THEME_ID&><ui=UI_LLCC&><wopisrc=WOPI_SOURCE&>&"/>
  <action name="view" ext="docx" urlsrc="https://<editor_address/hosting/wopi?documentType=word&mode=view&<rs=DC_LLCC&><dchat=DISABLE_CHAT&><e=EMBEDDED&><fs=FULLSCREEN&><hid=HOST_SESSION_ID&><rec=RECORDING&><sc=SESSION_CONTEXT&><thm=THEME_ID&><ui=UI_LLCC&><wopisrc=WOPI_SOURCE&>&"/>
  </app>
 </net-zone>
 <proof-key oldvalue="BgIA..." oldmodulus="qnro3n..." oldexponent="AQAB" value="BgIA..." modulus="qnro3n..." exponent="AQAB"/>
</wopi-discovery>

使用的属性包括：

<action> – 对于某一文件格式，由ONLYOFFICE编辑器支持的操作
<ext> – 文件格式扩展
<requires> – REST API实现中需要的方法，以执行该操作
<urlsrc> – 文件操作初始化的地址

如何创建编辑器页面

为了创建ONLYOFFICE编辑器的实例，WOPI主机创建一个带有<form> 和<ifraime>元素的页面。

我们使用onlyoffice-owncloud-wopi资源库中的示例页面：

<form id="office_form" name="office_form" target="office_frame" action="<?php p($_["actionUrl"]) ?>" method="post">
    <input name="access_token" value="<?php p($_["token"]) ?>" type="hidden" />
    <input name="access_token_ttl" value="<?php p($_["tokenttl"]) ?>" type="hidden" />
</form>

<iframe name="office_frame" id="office_frame" title="Office Frame" allowfullscreen="true"></iframe>

 <script>
        document.getElementById("office_form").submit();
</script>

 <style>
        .....
</style>

在这种情况下，表单提交转到actionUrl。它是由discovery提供的urlsrc生成的，包括用于初始化一些设置的参数：文件格式、编辑器模式、界面语言等。

下面是actionUrl的例子：

https://<editor_address>/hosting/wopi?documentType=word&mode=edit&wopisrc=https://<host_address>/wopi/files/1&lang=en

wopisrc参数指向主机的REST API，用于执行操作。

access_token 和access_token_ttl表单字段进一步用来访问REST API。

REST API的描述

REST API中的每个操作都对应于一个不同的请求类型和从wopisrc生成的url ，其中{fileid}是文件标识符。

access_token参数添加到url中以控制REST API的访问。

响应的一般状态代码包括：

200 OK - 成功
401 Unauthorized - 无效的令牌
404 Not Found - 找不到fileid资源

CheckFileInfo: GET /wopi/files/{fileid}

CheckFileInfo: GET /wopi/files/{fileid} 是对所有操作进行的运行，为ONLYOFFICE编辑器提供关于文件和当前用户访问权限的信息。

响应包括一组JSON格式的属性，其中有以下强制性的字段：

BaseFileName – 文件名称
OwnerId – 文件所有者的ID
Size – 文件大小
UserId – 当前用户的ID
Version – 文件的版本为字符串。对于每个文件版本，这个值是唯一的。

GetFile: GET /wopi/files/{fileid}/content

GetFile: GET /wopi/files/{fileid}/content 是从主机下载文件内容的操作。

请求头包括X-WOPI-MaxExpectedSize，它规定ONLYOFFICE编辑器可以处理最大文件大小的参数。如果请求文件的大小超过这个参数，主机应该回应为412 Precondition failed。

响应头包括 X-WOPI-ItemVersion，它指出下载文件的版本。该文件的版本必须与CheckFileInfo的Version值相匹配。

PutFile: POST /wopi/files/{fileid}/content

PutFile: POST /wopi/files/{fileid}/content是保存修改的文件的操作。

请求头包括以下参数：

X-WOPI-Override – 强制性的PUT字符串
X-WOPI-Lock – 强制性的锁标识符字符串
X-WOPI-Editors – 字符串，包含对文件进行修改的用户ID。

响应包括以下参数：

X-WOPI-Lock – 锁标识符字符串。如果响应是409，它就设置。如果响应是200，它就不设置。
X-WOPI-ItemVersion – 修改文件的版本必须与CheckFileInfo的Version值相匹配。

当文件在修改时，当前锁的ID和来自X-WOPI-Lock头的锁被检查。如果锁是有效的，文件就会被覆盖，并产生200 OK响应。否则，响应是409 Conflict。

如果主机有文件大小的限制，而修改的文件超过这个限制，响应是413 Request Entity Too Large。

Lock: POST /wopi/files/{fileid}

Lock: POST /wopi/files/{fileid} 是主机上的文件锁定操作。在编辑会话期间，该文件不得被第三方应用程序修改。

请求头包括以下参数：

X-WOPI-Override – 强制性的LOCK字符串
X-WOPI-Lock – 强制性的锁标识符字符串

响应标头包括以下参数：

X-WOPI-Lock – 强制性的锁标识符字符串。如果响应是409 Conflict，它是强制性的。如果响应是200 OK，它是可选的。
X-WOPI-LockFailureReason是在出现锁定错误时设置的，响应是409 Conflict。
X-WOPI-ItemVersion – 文件版本，必须与CheckFileInfo的Version值相匹配。

文件上传后，ONLYOFFICE编辑器会请求锁定该文件。如果该文件没有被锁定，则会以200 OK的响应进行锁定。

如果文件已经被锁定，将对照当前锁的ID和来自X-WOPI-Lock header头的锁进行检查。如果这些锁匹配，则执行RefreshLock，用200 OK响应更新计时器。否则，响应是409 Conflict。

RefreshLock: POST /wopi/files/{fileid}

RefreshLock: POST /wopi/files/{fileid}是更新锁定计时器的操作。

请求头包括以下参数：

X-WOPI-Override – 强制性的REFRESH_LOCK字符串
X-WOPI-Lock – 强制性的锁标识符字符串

响应标头包括以下参数：

X-WOPI-Lock – 强制性的锁标识符字符串。如果响应是409 Conflict，它是强制性的。如果响应是200 OK，它是可选的。
X-WOPI-LockFailureReason 是在出现锁定错误时设置的，响应是409 Conflict。

默认的锁定期是30分钟。如果编辑会话持续时间超过30分钟，文件将被解锁。为了避免这种情况，ONLYOFFICE编辑器会再次重复更新30分钟的锁定计时器。

Unlock: POST /wopi/files/{fileid}

Unlock: POST /wopi/files/{fileid} 是文件解锁的操作。

请求头包括以下参数：

X-WOPI-Override – 强制性的UNLOCK字符串,
X-WOPI-Lock – 强制性的锁标识符字符串。

响应标头包括以下参数：

X-WOPI-Lock – 当前的锁标识符字符串。如果响应是409 Conflict，它是强制性的。如果响应是200 OK，它是可选的。
X-WOPI-LockFailureReason 是在出现锁定错误时设置的，响应是409 Conflict。

如何自定义界面

我们可以通过两种方式来定制界面：

1. 在CheckFileInfo将定制参数丢入JSON。例如：

CloseUrl 激活ONLYOFFICE编辑器关闭的按钮。当点击它时，您将重定向到通过的URL。
FileSharingUrl 激活文档中的共享按钮。当点击它时，您会转到新标签中的共享页面。所传递的URL必须与共享页面相匹配。
PostMessageOrigin指定执行PostMessage的主机页面的域。
FileVersionPostMessage表示对上一个文件版本请求的PostMessage支持。

2. PostMessage功能： PostMessage允许在浏览器中的iframe存储和ONLYOFFICE Docs之间交换信息。它允许在线办公框架与它的父主机页面进行沟通。

主机页面提供一个配置的消息处理程序。根据来自编辑器的消息的类型，ONLYOFFICE会执行某些操作：

window.addEventListener(‘message’, function(event) {
var msg = JSON.parse(event.data);
}, false)

信息的例子包括:

UI_Close
UI_Edit
UI_FileVersions
UI_Sharing

为了激活特定类型的消息，我们将某个参数传递给CheckFileInfo。例如，为了查看文件版本历史，我们将CheckFileInfo中的FileVersionPostMessage参数设置为true。

总结

这些就是在ONLYOFFICE Docs中使用WOPI主要的方面。有的基础知识也可以在API documentation中找到。

目前，我们还没有实现所有的WOPI标准集成方法，例如，界面定制功能。因此，ONLYOFFICE的开发人员在执行进一步的改进的过程中。SharePoint是一种现成的WOPI集成，有内置的WOPI功能。这样一来，编辑器就可以通过其Management Shell Console轻松连接到SharePoint。此外，一些集成商，如FileCloud和OpenKM，已经通过WOPI嵌入了ONLYOFFICE编辑器。