如何使用 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文档服务器的服务器名称

请求参数

参数	说明	类型	必要性
filetype	来源文档类型	字符串	必须项
key	文档辨识符id号，用来区分文档	字符串	必须项
outputtype	设定要转换为的文档类型，除了可以用后缀名区分之外，也可以用类型设定ooxml 开放文档格式，即docx、docm、xlsx、xlsm、pptx、pptmodf 开源格式即odt、ods、odp	字符串	必须项
token	以令牌形式添加到文档服务器配置的加密签名。	字符串	依据配置而必须项
url	文档的绝对路径，使用本地链接时请务必添加令牌，否则会报错	字符串	必须项

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

文本文档格式表

输入格式

输出格式

bmp

docm

docx

docxf

dotm

dotx

epub

fb2

gif

html

jpg

odt

ott

pdf

pdfa

png

rtf

txt

djvu

●

○

○

○

○

○

○

○

●

○

●

○

○

●

●

●

○

○

doc

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

docm

●

○

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

docx

●

●

○

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

docxf

●

●

●

○

●

●

●

●

●

●

●

●

●

●

●

●

●

●

dot

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

dotm

●

●

●

●

○

●

●

●

●

●

●

●

●

●

●

●

●

●

dotx

●

●

●

●

●

○

●

●

●

●

●

●

●

●

●

●

●

●

epub

●

●

●

●

●

●

○

●

●

●

●

●

●

●

●

●

●

●

fb2

●

●

●

●

●

●

●

○

●

●

●

●

●

●

●

●

●

●

fodt

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

htm

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

html

●

●

●

●

●

●

●

●

●

○

●

●

●

●

●

●

●

●

mht

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

mhtml

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

odt

●

●

●

●

●

●

●

●

●

●

●

○

●

●

●

●

●

●

ott

●

●

●

●

●

●

●

●

●

●

●

●

○

●

●

●

●

●

oxps

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

pdf

●

●

●

●

●

●

●

●

●

●

●

●

●

○

●

●

●

●

rtf

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

○

●

stw

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

sxw

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

txt

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

○

wps

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

wpt

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

xml

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

xps

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

●

表格文档格式表

输入格式

输出格式

bmp

csv

gif

jpg

ods

ots

pdf

pdfa

png

xlsm

xlsx

xltm

xltx

csv

●

○

●

●

●

●

●

●

●

●

●

●

●

et

●

●

●

●

●

●

●

●

●

●

●

●

●

ett

●

●

●

●

●

●

●

●

●

●

●

●

●

fods

●

●

●

●

●

●

●

●

●

●

●

●

●

ods

●

●

●

●

○

●

●

●

●

●

●

●

●

ots

●

●

●

●

●

○

●

●

●

●

●

●

●

sxc

●

●

●

●

●

●

●

●

●

●

●

●

●

xls

●

●

●

●

●

●

●

●

●

●

●

●

●

xlsb

●

●

●

●

●

●

●

●

●

●

●

●

●

xlsm

●

●

●

●

●

●

●

●

●

○

●

●

●

xlsx

●

●

●

●

●

●

●

●

●

●

○

●

●

xlt

●

●

●

●

●

●

●

●

●

●

●

●

●

xltm

●

●

●

●

●

●

●

●

●

●

●

○

●

xltx

●

●

●

●

●

●

●

●

●

●

●

●

○

xml

●

●

●

●

●

●

●

●

●

●

●

●

●

演示文档格式表

输入格式

输出格式

bmp

gif

jpg

odp

otp

pdf

pdfa

png

potm

potx

ppsm

ppsx

pptm

pptx

dps

●

●

●

●

●

●

●

●

●

●

●

●

●

●

dpt

●

●

●

●

●

●

●

●

●

●

●

●

●

●

fodp

●

●

●

●

●

●

●

●

●

●

●

●

●

●

odp

●

●

●

○

●

●

●

●

●

●

●

●

●

●

otp

●

●

●

●

○

●

●

●

●

●

●

●

●

●

pot

●

●

●

●

●

●

●

●

●

●

●

●

●

●

potm

●

●

●

●

●

●

●

●

○

●

●

●

●

●

potx

●

●

●

●

●

●

●

●

●

○

●

●

●

●

pps

●

●

●

●

●

●

●

●

●

●

●

●

●

●

ppsm

●

●

●

●

●

●

●

●

●

●

○

●

●

●

ppsx

●

●

●

●

●

●

●

●

●

●

●

●

●

●

ppt

●

●

●

●

●

●

●

●

●

●

●

●

●

●

pptm

●

●

●

●

●

●

●

●

●

●

●

●

○

●

pptx

●

●

●

●

●

●

●

●

●

●

●

●

●

○

sxi

●

●

●

●

●

●

●

●

●

●

●

●

●

●

请求示例

发送给文档转换服务的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参数值。当生成结果文件的链接时，会使用请求包所用的同一个服务器名。

参数	说明	类型	示例
endConvert	转换是否完成	boolean	true
error	错误信息代码	integer	-3
fileType	输出文件的扩展名	string	docm
fileUrl	输出文件的链接，只有当endConvert参数为真时才会出现	string	“https://documentserver/url-to-converted-document.pdf”
percent	文件转换执行进度 如果endConvert为真则此为100	integer	100

返回为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
 }

错误码信息：

错误码	意义
-1	未知错误
-2	转换超时
-3	转换出错
-4	下载过程出错
-5	密码错误
-6	访问转换结果数据库出错
-7	输入错误
-8	无效令牌

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

总结

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