【onlyoffice中文指南】13-转换API接口

【onlyoffice中文指南】13-转换API接口（收藏转载）

源文：http://events.jianshu.io/p/adb5941b4628

转换 API

对于与文档转换服务的交互，使用 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 必需的

* -在表中可以看到转换的可能性在你的文件转换成最知名的文件格式，其中输入格式列对应的值，文件类型参数和 输出格式列对应的值输出类型参数。

文本文档文件格式

 
image.png

电子表格文件格式

 
image.png

演示文稿格式

 
image.png

发送到文档转换服务的 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 令牌无效。

实际示例：

 
image.png
 
 
posted @ 2022-09-16 16:05  baivfhpwxf  阅读(2291)  评论(0)    收藏  举报