微网站建设及开发,wordpress登陆过程,用心做电影的网站,驻马店公司做网站作者#xff1a;天哥
上一期我们介绍了 ONLYOFFICE 的文档生成器API接口函数库。这一期我们继续介绍ONLYOFFICE 的文件转换API接口函数库。 为什么要使用 ONLYOFFICE 转换API
ONLYOFFICE 转换 API 有助于转换大部分类型的Office文档#xff1a;文本、表格、幻灯片、表单、P…作者天哥
上一期我们介绍了 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幻灯片演示文件 如下图所示文档编辑临时转换格式 使用者在本地计算机硬盘上选择一个文件将其上传到文档管理器。文档管理器上传所选择的文件到文档存储服务。文档存储服务发送该上传的文件到ONLYOFFICE文档服务器的文档转换服务调用转换API将其转换为开放文档格式。文档转换服务将选择的文件转换为开放文档格式。文档存储服务下载转换好的文件。
文档输出
当使用者需要下载为某种格式的时候ONLYOFFICE文档服务器将存储在文档存储服务的相应文件转换为使用者所需的格式。 如下图所示文档转换格式输出过程 使用者在文档管理器上选择文件并选择以某种格式下载。文档管理器将使用者的这个操作翻译为一个内部的网络request请求发送给文档存储服务。文档存储服务发送这个上传的文件给ONLYOFFICE文档服务器的文档转换服务使用转换API来来转换格式。文档转换服务将选择的文件转换到指定的格式。转换完成文档存储服务下载最终文件。文档存储服务通知文档管理器转换已完成。文档管理器下载最终文件。
文档转换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 version1.0 encodingutf-8?FileResultEndConvertTrue/EndConvertFileTypedocm/FileTypeFileUrlhttps://documentserver/url-to-converted-document.pdf/FileUrlPercent100/Percent/FileResult
返回为JSON格式的示例
{endConvert: true,fileType: docm,fileUrl: https://documentserver/url-to-converted-document.pdf,percent: 100}
异步模式的响应包的XML格式示例
?xml version1.0 encodingutf-8?FileResultEndConvertFalse/EndConvertFileType/FileTypeFileUrl/FileUrlPercent95/Percent/FileResult
异步模式的响应包的JSON格式示例
{endConvert: false,percent: 95}
返回一个错误码的响应包XML格式示例
?xml version1.0 encodingutf-8?FileResultError-3/Error/FileResult
返回一个错误码的响应包JSON格式示例
{error: -3}
错误码信息 错误码 意义 -1 未知错误 -2 转换超时 -3 转换出错 -4 下载过程出错 -5 密码错误 -6 访问转换结果数据库出错 -7 输入错误 -8 无效令牌 例如-8将在浏览器中得到如下画面 总结
使用文件转换API将极大的方便前端开发者将各种类型的办公文件进行格式的互相转换为最终使用者提供无障碍的使用体验。
