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编辑器。