【onlyoffice中文指南】13-转换API接口
【onlyoffice中文指南】13-转换API接口(收藏转载)
源文:http://events.jianshu.io/p/adb5941b4628
对于与文档转换服务的交互,使用 POST 请求。请求参数在请求正文中以 JSON 格式输入。请求被发送到https://documentserver/ConvertService.ashx地址,其中documentserver是安装了 ONLYOFFICE 文档服务器的服务器的名称。
在4.2 版之前的ONLYOFFICE 文档服务器中,使用了带有QueryString参数的 GET 请求。
参数及其说明:
Parameters and their description:
范围 | 描述 | 类型 | 在场 |
---|---|---|---|
Async | 定义转换请求类型:异步与否。<br />支持的值:<br /> true<br /> false<br />当使用异步请求类型时,立即形成响应。<br />在这种情况下,要获得结果,必须在转换完成之前发送不更改参数的请求。<br />默认值为false。 | boolean | 可选的 |
codePage | 定义从csv或txt格式转换时的文件编码。 <br />主要支持的值:<br />932 - 日语(Shift-JIS)<br />950 - 中国繁体(Big5)<br />1250 - 中欧(视窗)<br />1251 - 西里尔文(视窗)<br />65001 - Unicode (UTF-8)。<br />您可以在此文件中找到所有支持的值。 | integer | 可选的 |
Delemiter | 定义从csv格式转换时用于分隔值的分隔符。 <br />支持的值:<br />0 - 没有分隔符<br />1 - 标签<br />2 - 分号<br />3 - 冒号<br />4 - 逗号<br />5 - 空间。 | integer | 可选的 |
fileType* | 定义要转换的文档文件的类型。 | string | 必需的 |
Key | 定义用于明确标识文档文件的文档标识符。 | string | 必需的 |
outputtype* | 定义生成的转换文档类型。 | string | 必需的 |
password | 如果文档文件受密码保护,则定义该文件的密码。 | string | 可选的 |
region | 定义从电子表格格式转换为pdf时货币和日期和时间的默认显示格式。使用四个字母(en-US、fr-FR等)语言代码进行设置。默认值为en-US。 | string | 可选的 |
spreadsheetLayout | 定义用于将电子表格转换为 pdf 的设置。 | object | 可选的 |
spreadsheetLayout.fitToHeight | 设置转换区域的高度,以页数为单位。默认值为0。 | integer | 可选的 |
spreadsheetLayout.fitToWidth | 设置转换区域的宽度,以页数为单位。默认值为0。 | integer | 可选的 |
spreadsheetLayout.gridLines | 允许在输出 PDF 文件中包含或不包含网格线。默认值为false。 | boolean | 可选的 |
spreadsheetLayout.headings | 允许在输出 PDF 文件中包含或不包含标题。默认值为false。 | boolean | 可选的 |
spreadsheetLayout.ignorePrintArea | 确定是否忽略为电子表格文件选择的打印区域。默认值为true。 | boolean | 可选的 |
spreadsheetLayout.margins | 设置输出 PDF 文件的边距。 | object | 可选的 |
spreadsheetLayout.margins.bottom | 设置输出 PDF 文件的下边距。默认值为19.1 毫米。 | string | 可选的 |
spreadsheetLayout.margins.left | 设置输出 PDF 文件的左边距。默认值为17.8mm。 | string | 可选的 |
spreadsheetLayout.margins.right | 设置输出 PDF 文件的右边距。默认值为17.8mm。 | string | 可选的 |
spreadsheetLayout.margins.top | 设置输出 PDF 文件的上边距。默认值为19.1 毫米。 | string | 可选的 |
spreadsheetLayout.orientation | 设置输出 PDF 文件的方向。可能是****landscape****,****portrait****。默认值为****portrait****。 | string | 可选的 |
spreadsheetLayout.pageSize | 设置输出 PDF 文件的页面大小。 | object | 可选的 |
spreadsheetLayout.pageSize.height | 设置输出 PDF 文件的页面高度。默认值为297 毫米。 | string | 可选的 |
spreadsheetLayout.pageSize.width | 设置输出 PDF 文件的页面宽度。默认值为210 毫米。 | string | 可选的 |
spreadsheetLayout.scale | 允许设置输出 PDF 文件的比例。默认值为100。 | integer | 可选的 |
thumbnail | 将图像格式(bmp、gif、jpg、png)指定为outputtype时,定义缩略图的设置。 | object | 可选的 |
thumbnail.aspect | 定义使图像适合指定的高度和宽度的模式。<br />支持的值:<br />0 - 拉伸文件以适应高度和宽度<br />1 - 保持图像的方面<br />2 - 在这种情况下,不使用宽度和高度设置。取而代之的是,页面的公制尺寸转换为 96dpi 的像素。例如,A4 (210x297mm) 页面将变成尺寸为 794x1123pix 的图片。<br />默认值为:2。 | integer | 可选的 |
thumbnail.first | 定义是仅为第一页还是为所有文档页面生成缩略图。<br />如果为 false,则将创建包含所有页面缩略图的 zip 存档。<br />默认值为true, | boolean | 可选的 |
thumbnail.height | 以像素为单位定义缩略图高度。默认值为100。 | integer | 可选的 |
thumbnail.width | 以像素为单位定义缩略图宽度。默认值为100。 | integer | 可选的 |
title | 定义转换后的文件名。 | string | 可选的 |
token | 定义以令牌形式添加到文件服务器配置的加密签名。 | string | 配置要求 |
url | 定义要转换的文档的绝对 URL。使用本地链接时请务必添加令牌。否则会出现错误。 | string | 必需的 |
* -在表中可以看到转换的可能性在你的文件转换成最知名的文件格式,其中输入格式列对应的值,文件类型参数和 输出格式列对应的值输出类型参数。
文本文档文件格式
电子表格文件格式
演示文稿格式
发送到文档转换服务的 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是安装文档管理器和文档存储服务的服务器的名称。请参阅它的工作原理部分以了解有关文档服务器服务客户端-服务器交互的更多信息。
发送到文档转换服务的 JSON 对象示例,用于将受密码保护的文件从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"
}
其中example.com是安装文档管理器和文档存储服务的服务器的名称。请参阅它的工作原理部分以了解有关文档服务器服务客户端-服务器交互的更多信息。
发送到文档转换服务的 JSON 对象示例,用于生成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"
}
其中example.com是安装文档管理器和文档存储服务的服务器的名称。请参阅它的工作原理部分以了解有关文档服务器服务客户端-服务器交互的更多信息。
发送到用于将电子表格文件转换为pdf格式的文档转换服务的 JSON 对象示例
{
"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"
}
其中example.com是安装文档管理器和文档存储服务的服务器的名称。请参阅它的工作原理部分以了解有关文档服务器服务客户端-服务器交互的更多信息。
JSON 对象示例包含发送到文档转换服务的 JSON Web 令牌,用于将文件从docx格式转换为pdf格式
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.U-YAfuuy7clWjn-xOncfJ-sxVG5DlcYn0AOzJYkoR0M"
}
其中example.com是安装文档管理器和文档存储服务的服务器的名称。请参阅它的工作原理部分以了解有关文档服务器服务客户端-服务器交互的更多信息。
请求结果以 XML 格式返回。以接收JSON格式需要在HTTP请求报头指定的响应接受与所述值应用/ JSON(得自4.3版本)。在形成到结果文件的链接时,使用与转换请求相同的服务器名称。
XML 格式的响应示例
在形成到结果文件的链接时,使用与转换请求相同的服务器名称。
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
<EndConvert>True</EndConvert>
<FileUrl>https://documentserver/url-to-converted-document.pdf</FileUrl>
<Percent>100</Percent>
</FileResult>
JSON 格式的响应示例
在形成到结果文件的链接时,使用与转换请求相同的服务器名称。
{
"endConvert": true,
"fileUrl": "https://documentserver/url-to-converted-document.pdf",
"percent": 100
}
XML 格式的异步请求中间响应示例(带有参数async=true)
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
<EndConvert>False</EndConvert>
<FileUrl></FileUrl>
<Percent>95</Percent>
</FileResult>
JSON 格式的对异步请求的中间响应示例(带有参数async=true)
{
"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 | 令牌无效。 |
实际示例: