将 ONLYOFFICE 文档编辑器与 С# 群件平台集成

在本文中，我们会向您展示 ONLYOFFICE 文档编辑器与其自有的协作平台集成。

ONLYOFFICE 是一款开源办公套件，包括文本文档、电子表格和演示文稿编辑器。这款套件支持用户通过文档编辑组件扩展第三方 web 应用的功能，可直接在应用的界面中使用。在之前的几篇文章中，我们向您展示了如何实现这种集成（请参考 Node.js 或 Python 示例）。

在本文中，我们会向您展示一个最真实的集成案例，是 ONLYOFFICE 文档编辑器与自有协作平台集成。

ONLYOFFICE****Groups

ONLYOFFICE Groups（社区服务器）是一个免费的开源协作系统，使用 C# 编写，根据 GNU GPL v3.0 分发。它包括文档和项目管理、CRM、电子邮件聚合器、日历、用户数据库、博客、论坛、投票、维基和即时通讯工具。

ONLYOFFICE Groups 是完整的自托管解决方案的一部分，支持用户在自己的服务器上部署功能齐备的私人网络办公室。它有免费的社区版和企业版，企业版具备更多系统管理选项和增强版的安全工具，适合更大团队使用。

集成清单

如要将 ONLYOFFICE 文档编辑器与协作平台无缝集成，所需的最重要的权限清单如下：

1．添加定制代码

2．匿名访问权限，用于下载和保存文件。这意味着我们的编辑器仅在服务器端与协作平台通信，不涉及客户端的任何用户授权数据（浏览器 cookie）

3．添加界面按钮

4．与协作平台模块（DMS、CRM、项目、邮件）集成

5．打开一个新页面，用于执行脚本来添加编辑器

6．能够指定文档服务器连接设置

我们来看看，如何根据这份清单来实施集成：

1**．**添加代码

由于 ONLYOFFICE 编辑器是所有 ONLYOFFICE 解决方案的中心元素，在我们的协作系统中嵌入编辑功能在开始就是开发工作的主要部分。

此外，ONLYOFFICE 支持用户在社区服务器中添加自定义模块（如自己的 CRM 系统），为添加的模块创建 API。GitHub 上有相关示例项目。

2**．**匿名访问

我们实施了一个回调处理程序，处理从 ONLYOFFICE 文档服务器到协作平台（即 DMS）的请求。它们之间直接交互，不需要浏览器 cookie 等用户验证数据；相反，它基于 JWT 技术，使用请求签名验证。

文档服务器使用其配置文件中所谓的"密钥"将 JWT 添加到请求中。之后 DMS 会检查 JWT 密钥是否与其配置中的密钥一致。只有签名验证成功，回调处理程序才会执行被请求的操作。

如下是 JWT 验证请求的处理过程：

public class FileHandler : IHttpAsyncHandler
{
    public override void OnProcessRequest(HttpContext context)
    {
        using (var receiveStream = context.Request.InputStream)
        using (var readStream = new StreamReader(receiveStream))
        {
            //request body
            var body = readStream.ReadToEnd();

            //request data
            var data = JToken.Parse(body);
            var callbackData = data.ToObject<CallbackData>();

            //request token
            var jwtString = JsonWebToken.Decode(callbackData.Token, Config.JwtSecret);
            var jwtData = JObject.Parse(jwtString);
            if (jwtData == null)
            {
                throw new ArgumentException("Document Service request token is incorrect");
            }

            //request data from JWT
            callbackData = jwtData.ToObject<CallbackData>();
            result = ProcessData(callbackData);
            context.Response.Write(result ?? "{\"error\":0}");
        }
    }
    ...
}

响应应该是：

{"error":0}

根据请求的状态，特定的操作被执行：

public string ProcessData(CallbackData callbackData)
{
    switch (callbackData.Status)
    {
        case NotFound:
        case Closed:
            FileTracker.Remove(callbackData.key);
            break;

        case Editing:
            ProcessEdit(callbackData);
            break;

        case MustSave:
        case Corrupted:
            return ProcessSave(callbackData);
    }
    return null;
}

3**．**添加按钮

最重要的两个操作一定是打开查看和编辑（相应是"预览"和"编辑"按钮）。我们可在界面中实施其他操作按钮，则可支持用户执行以下操作：

• 移动
• 复制
• 下载，可以选择所需的格式
• 重命名
• 删除
• 查看文档的版本历史
• 设置文件访问权限，包括共享设置、可为门户网站用户生成链接、阻止/解除阻止文档，以及通过电子邮件发送文档。通过电子邮件发送文档是通过与邮件模块集成实现（请参考下文）。

4**．**与模块集成

除按钮外，还有一些操作需要文档服务器与其他服务或模块交互。例如，我们通过转换服务，在文档管理的几个阶段转换文件，如用户上传、打开或下载文档时。但需要注意的是，因为 Office Open XML 是我们的核心格式，DOCX、XLSX 和 PPTX 文件是会被直接处理，而其他的文件格式都会被转换为 OOXML。这样做是为了加速文件处理，提升互操作性。

用户不仅可以在文件管理系统中处理文档（我们在之前一篇文章中有详细介绍），也可以在 CRM、项目和邮件中进行。

在 CRM 模块中，用户可以：

• 将文档附加到 CRM 商机和案例，
• 在 CRM 中直接创建新的文档、工作表和演示文稿（同样适用于商机和案例），
• 打开、编辑或下载附件文档。

用户可以从 CSV 文件将联系人批量导入 CRM，也可以将客户数据库导出为 CSV 文件：

在"项目"模块中，我们为文档、电子表格和演示文稿建立了一个单独的文件夹（项目文档）。

用户可以将文档附到项目任务和讨论中，可以直接在"项目"模块中创建新文件。用户在管理附件文件时，可以对其进行编辑、下载或删除操作。

在"邮件"模块中，我们是这样实现集成的：除了将本地驱动器中的文档、电子表格和演示文稿附加到邮件之外，用户还可以将存储在"文档"模块中的文件添加为附件。如果文件大小超出限制，建议用户发送时使用所需文档的链接。

在这种情况下，文件的链接会被插入邮件正文中。在发送邮件之前，用户需要为所有链接指向的附件文件设置访问权限。之后收件人点击邮件中的链接时，会基于被指定的访问权限，在在线查看器或编辑器中打开文档。

ONLYOFFICE 用户收到有文档附件的邮件时，可以：

• 下载附件
• 在浏览器中查看文件
• 打开文档、电子表格或演示文稿进行编辑（在这种情况下，如果格式不是 OOXML，系统会自动将其转换为 .docx/.xlsx/.pptx 格式，并将其保存到"文档"中）
• 将文件保存到"文档"模块，会选择所需的文件夹

用户可通过"邮件"设置，在"文档"模块选择任意文件夹，电子邮件信息中的所有附件都会被自动保存在这个文件夹中：

此外，在"CRM"和"项目"模块中，我们可以通过 ONLYOFFICE 文档生成工具"文档生成器"生成报告。通过这款工具，您无需实际运行文档处理编辑器即可生成文档。它还支持开发人员使用模板自动生成文档，或将数据库中的数据插入文档。

5**．**用编辑器打开页面

使用编辑器打开新页面时，会生成初始化配置。发送至编辑器的主要参数包括定义文件类型的参数、界面语言 (editorConfig.lang = "en-US")，以及每个用户的权限列表，也就是说，我们会检查用户是否拥有相应的权限：包括打开和编辑文档、执行其他操作（发表评论、下载、重命名文件等）：

var config = {
   "document":{
      "fileType":"docx",
      "info":{
         "author":"Me",
         "created":"3\/29\/2019 10:06 PM",
         "folder":"My Documents",
         "sharingSettings":[
            {
               "permissions":"Full Access",
               "user":"Me"
            }
         ]
      },
      "key":"kouNPg1",
      "permissions":{
         "changeHistory":true,
         "comment":true,
         "download":true,
         "edit":true,
         "fillForms":true,
         "print":true,
         "rename":true,
         "review":true
      },
      "title":"ONLYOFFICE Sample Document.docx",
      "url":"https:\/\/demo.onlyoffice.com\/demo.docx"
   },
   "documentType":"text",
   "editorConfig":{
      "callbackUrl":"https:\/\/demo.onlyoffice.com\/filehandler.ashx",
      "lang":"en-US",
      "mode":"edit",
      "user":{
         "id":"9acf7169b737",
         "name":"John Smith"
      }
   },
   "type":"desktop"
}

6**．**连接设置

用户可以基于解决方案指定或不指定文档服务器连接设置。

在我们自己托管的 ONLYOFFICE 云服务中，连接设置对用户隐藏，由我们在服务器配置中进行设置。

ONLYOFFICE 服务器解决方案的用户可以指定安装 ONLYOFFICE 编辑器的服务器地址。门户管理员可在"设置"页面的"集成"板块进行相关设置：

ONLYOFFICE 文档和社区服务器通常会被安装在同一台机器上。在这种情况下，您的网络配置可能不允许它们之间使用公共地址收发请求。因此，需要另外两个字段（如上方截图所示）来指定 ONLYOFFICE 文档服务器地址，以便从社区服务器发出和接收内部请求。

管理员保存设置时，门户和编辑器之间的交互会被检查，以确保连接正确。

如要详细了解 ONLYOFFICE 文档编辑器如何与其他服务集成，请参阅 API 文档。

如果您想尝试将 ONLYOFFICE 文档编辑器与协作平台结合使用，并查看其集成情况，您可以在私人服务器上部署 ONLYOFFICE工作区，即刻开始免费试用。