如何使用 ONLYOFFICE API 转换办公文档格式

作者：天哥

上一期我们介绍了 ONLYOFFICE 的文档生成器API接口函数库。这一期我们继续介绍ONLYOFFICE 的文件转换API接口函数库。

为什么要使用 ONLYOFFICE 转换API

ONLYOFFICE 转换 API 有助于转换大部分类型的Office文档：文本、表格、幻灯片、表单、PDF、电子书等。

支持大部分流行的格式：将文档、表格或幻灯片转化为PDF，将课本转化为电子书，将演示文稿转换为图像文件，等等。ONLYOFFICE支持超过50种文档格式。

高级设置：添加转换设置，以便转换CSV文件时定义分隔符，转换电子表格时定义默认货币显示模式，或以便设置输出PDF文件的页面大小和页边距，等等。并提供完备的API文档，可以参考所有可用的选项。

高质量的转换：ONLYOFFICE不断改进服务，为所有转换类型提供高质量的结果。

安全性：ONLYOFFICE的开放源代码可在GitHub上找到，这确保ONLYOFFICE的透明度和可靠性。JSON网络令牌保护文件免受未经授权的访问。

工作原理

ONLYOFFICE文档服务器对文档的处理是非常简单的，但是需要理解其工作原理，当你点击一个文档在浏览器页面里打开的时候、保存文档的时候、或者从计算机上传到服务器的时候，它是如何工作的。

使用者和文档之间的交互由客户端和服务器端共同实现。下面介绍一下一些基本概念。

客户端包括：

• 文档管理器：文档的列表显示在使用者的浏览器里面，使用者可以选择文档对其操作，根据对使用者赋予的权限，他可以打开文档阅览或者编辑，或者分享给其他使用者。
• 文档编辑器：文档阅览和编辑界面，包含几乎所有一直的文档编辑功能特征，作为一个中介媒介，连接起来了使用者和文档编辑服务器。

服务器端包括：

• 文档存储服务：存储所有文档的服务器端，将文档以设定的权限提供给使用者。他提供了文档的ID号和文档的链接的信息发送给文档管理器，使用者就可以在浏览器里看到文档列表。
• 文档编辑服务：提供对文档进行阅览和编辑功能的服务器端，前提是使用者被赋予相应的权限，文档编辑器界面被用来访问所有的文档编辑服务的功能特征。
• 文档命令服务：提供执行特别命令操作的文档编辑服务。
• 文档转换服务：提供文档转换功能的服务器端，转换为开放文档格式Open XML，例如文本文档的docx、表格文档的xlsx、以及演示幻灯片的pptx，编辑或者下载。
• 文档生成器服务：不需要实际打开运行一个文档编辑器而通过API生成文档的服务。

注意，ONLYOFFICE文档服务器包含这个文档编辑器、文档编辑服务、文档命令服务、文档转换服务、以及文档生成器服务。而文档管理器和文档存储服务由ONLYOFFICE社区服务器Community Server提供，或者由其它开发集成商开发实现，在自己的服务器上安装部署ONLYOFFICE的文档服务器。

文档转换服务是ONLYOFFICE文档服务器的一部分，它使得使用者可以转换文件格式以便在文档编辑器中打开或者导出文件。有两种情况会使用到文档转换服务。

文档编辑需要临时转换

文档编辑器想要正确的处理文档，就需要将其转换为开放文档格式OpenXML： * docx文档文件 * xlsx表格文件 * pptx幻灯片演示文件 如下图所示，文档编辑临时转换格式：

1. 使用者在本地计算机硬盘上选择一个文件，将其上传到文档管理器。
2. 文档管理器上传所选择的文件到文档存储服务。
3. 文档存储服务发送该上传的文件到ONLYOFFICE文档服务器的文档转换服务，调用转换API将其转换为开放文档格式。
4. 文档转换服务将选择的文件转换为开放文档格式。
5. 文档存储服务下载转换好的文件。

文档输出

当使用者需要下载为某种格式的时候，ONLYOFFICE文档服务器将存储在文档存储服务的相应文件转换为使用者所需的格式。 如下图所示，文档转换格式输出过程：

1. 使用者在文档管理器上选择文件并选择以某种格式下载。
2. 文档管理器将使用者的这个操作翻译为一个内部的网络request请求发送给文档存储服务。
3. 文档存储服务发送这个上传的文件给ONLYOFFICE文档服务器的文档转换服务，使用转换API来来转换格式。
4. 文档转换服务将选择的文件转换到指定的格式。
5. 转换完成，文档存储服务下载最终文件。
6. 文档存储服务通知文档管理器转换已完成。
7. 文档管理器下载最终文件。

文档转换API

为了与文档转换服务交互，需要使用POST请求。请求参数以JSON格式输入到请求体中，请求需要发送至地址https://documentserver/ConvertService.ashx，这里的documentserver是ONLYOFFICE文档服务器的服务器名称

请求参数

此表只列举了必须项目，请求参数里可选的参数的细节，详见开发手册：ONLYOFFICE 转换 API

文本文档格式表

表格文档格式表

演示文档格式表

请求示例

发送给文档转换服务的JSON对象的示例，请求将docx文件转换为pdf文件：

{
     "async": false,
     "filetype": "docx",
     "key": "Khirz6zTPdfd7",
     "outputtype": "pdf",
     "title": "Example Document Title.docx",
     "url": "https://example.com/url-to-example-document.docx"
 }

其中example.com是文档管理器和文档存储服务所安装部署的服务器的地址。

将带有密码保护的docx文件转换为pdf文件：

{
     "async": false,
     "filetype": "docx",
     "key": "Khirz6zTPdfd7",
     "outputtype": "pdf",
     "password": "123456",
     "title": "Example Document Title.docx",
     "url": "https://example.com/url-to-example-document.docx"
 }

从docx文件生成png缩略图：

{
     "filetype": "docx",
     "key": "Khirz6zTPdfd7",
     "outputtype": "png",
     "thumbnail": {
         "aspect": 0,
         "first": true,
         "height": 150,
         "width": 100
     },
     "title": "Example Document Title.docx",
     "url": "https://example.com/url-to-example-document.docx"
 }

表格文件转为pdf格式：

{
     "filetype": "xlsx",
     "key": "Khirz6zTPdfd7",
     "outputtype": "pdf",
     "region": "en-US",
     "spreadsheetLayout": {
         "ignorePrintArea": true,
         "orientation": "portrait",
         "fitToWidth": 0,
         "fitToHeight": 0,
         "scale": 100,
         "headings": false,
         "gridLines": false,
         "pageSize": {
             "width": "210mm",
             "height": "297mm"
         },
         "margins": {
             "left": "17.8mm",
             "right": "17.8mm",
             "top": "19.1mm",
             "bottom": "19.1mm"
         }
     },
     "title": "Example Document Title.docx",
     "url": "https://example.com/url-to-example-spreadsheet.xlsx"
 }

响应回传参数

请求的结果返回来为XML格式，如果要得到JSON格式的响应，需要指定HTTP请求的ACCEPT头的application/json参数值。当生成结果文件的链接时，会使用请求包所用的同一个服务器名。

返回为XML格式的示例：

<?xml version="1.0" encoding="utf-8"?>
 <FileResult>
     <EndConvert>True</EndConvert>
     <FileType>docm</FileType>
     <FileUrl>https://documentserver/url-to-converted-document.pdf</FileUrl>
     <Percent>100</Percent>
 </FileResult>

返回为JSON格式的示例：

{
     "endConvert": true,
     "fileType": "docm",
     "fileUrl": "https://documentserver/url-to-converted-document.pdf",
     "percent": 100
 }

异步模式的响应包的XML格式示例：

<?xml version="1.0" encoding="utf-8"?>
 <FileResult>
     <EndConvert>False</EndConvert>
     <FileType></FileType>
     <FileUrl></FileUrl>
     <Percent>95</Percent>
 </FileResult>

异步模式的响应包的JSON格式示例：

{
     "endConvert": false,
     "percent": 95
 }

返回一个错误码的响应包XML格式示例：

<?xml version="1.0" encoding="utf-8"?>
 <FileResult>
     <Error>-3</Error>
 </FileResult>

返回一个错误码的响应包JSON格式示例：

{
     "error": -3
 }

错误码信息：

例如-8将在浏览器中得到如下画面

总结

使用文件转换API将极大的方便前端开发者，将各种类型的办公文件进行格式的互相转换，为最终使用者提供无障碍的使用体验。