文档生成器 API

对于与 Web 文档生成器服务的交互，使用 POST 请求。请求参数在请求正文中以 JSON 格式输入。请求被发送到 https://documentserver/docbuilder 地址，其中 documentserver 是安装了 ONLYOFFICE 文档的服务器的名称。

提示

从 8.1 版开始，建议将 shardkey 参数添加到查询字符串中，其中包含 key 值。例如，?shardkey=Khirz6zTPdfd7。这允许您对请求进行负载平衡。

备注

从 10.0 版本开始，可以通过服务器设置 services.CoAuthoring.server.docbuilderEnable 关闭文档生成器 API。在这种情况下，发送到 https://documentserver/docbuilder 地址的请求将被拒绝，并返回 HTTP 403 状态码。

请求参数

参数	类型	是否必填	描述
argument	object	非必填	要传递给创建的文档的参数。请参阅支持的属性了解如何使用参数的详细信息。
async	boolean	非必填	对文档生成器服务的请求类型：异步与否。当设置为 true 时，响应立即形成并包含一个 key。然后您必须使用此 key 发送请求进行轮询，直到文档生成完成（当 end 变为 true 时）。默认值为 false。
key	string	视情况而定	用于明确标识请求的请求标识符。key 在文档生成器服务端形成，并作为对第一个请求的响应返回。当使用异步请求时（async 参数设置为 true），key 不存在于第一个请求中，但必须存在于将在文档生成完成之前发送的所有后续请求中。使用同步请求时（async 参数设置为 false），不需要该参数。
token	string	配置要求	以令牌的形式添加到 ONLYOFFICE 文档配置的加密签名。
url	string	必填	.js 脚本文件的绝对 URL。

.js 脚本文件是一个 JavaScript 文件，使用 Office JavaScript API 来生成输出文档文件（文本文档、电子表格或演示文稿）。它使用 builder.CreateFile() 创建文档，使用 Office API 类来操作内容，使用 builder.SaveFile() 指定输出格式和名称，使用 builder.CloseFile() 完成文档处理。您可以在此处找到有关脚本文件语法的更多信息。一旦文档生成完成，将返回带有结果文件绝对 URL 的响应（见下文）。

备注

.js 脚本文件可以包含多个输出文件作为结果。文件生成完成后，它们的 URL 将在请求响应中返回。

警告

在脚本中使用 builder.OpenFile() 时，必须提供文件的绝对 URL（例如 https://example.com/document.docx），而不是本地路径。文档服务器需要从可公开访问的位置下载文件。

响应参数

请求结果以 JSON 格式返回。

参数	类型	示例	描述
end	boolean	true	文档生成是否完成。当值为 false 时，任务仍在处理中，响应中不包含 urls 参数。当值为 true 时，任务已完成，urls 参数将出现在响应中。
error	integer	-8	文档生成过程中发生的错误。可能的错误代码可在下方找到。
key	string	af86C7e71Ca8	文档生成任务的唯一标识符。如果请求中提供了 key 参数，则返回相同的值。如果在第一个异步请求中未提供 key 参数，则由文档生成器服务生成新的 key。请在所有后续轮询请求中使用此值。
urls	object	{"output.docx": "https://documentserver/..."}	包含生成的输出文件绝对 URL 的对象。对象键是 .js 脚本中指定的输出文件名。此参数仅在 end 值为 true 时存在。

示例脚本

下面是一个简单的 .js 脚本，用于创建包含 "Hello World!" 文本的文档：

builder.CreateFile("docx");
var oDocument = Api.GetDocument();
var oParagraph = oDocument.GetElement(0);
oParagraph.AddText("Hello World!");
builder.SaveFile("docx", "output.docx");
builder.CloseFile();

将此文件托管在可公开访问的服务器上，以便与下面的 API 请求一起使用。

示例

信息

在以下示例中，example.com 表示安装文档存储服务以及托管 .js 文件的服务器名称。要深入了解 ONLYOFFICE 文档服务的客户端-服务器交互机制，请参阅工作原理章节。

异步请求

步骤 1. 发送包含 .js 脚本文件 URL 的初始请求：

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": true,
    "url": "https://example.com/url-to-example-script.js"
  }'

响应：

{
  "key": "af86C7e71Ca8",
  "end": false
}

步骤 2. 使用返回的 key 轮询，直到 end 为 true：

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": true,
    "key": "af86C7e71Ca8"
  }'

响应：

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

同步请求

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js"
  }'

响应：

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

带令牌的异步请求

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3luYyI6dHJ1ZSwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1zY3JpcHQuZG9jYnVpbGRlciJ9.dzoTbRzSMa95Fpg34CjnF3ZUPdGA2CnBedFL_qOOxAs"
  }'

响应：

{
  "error": -8
}

信息

此示例演示了令牌无效时的错误响应。有关更多详细信息，请参阅错误代码部分。

带参数的同步请求

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js",
    "argument": {
      "key": "string",
      "key2": "string2"
    }
  }'

响应：

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

多个输出文件

一个 .js 脚本可以生成多个文件。例如：

builder.CreateFile("docx");
var oDocument = Api.GetDocument();
var oParagraph = oDocument.GetElement(0);
oParagraph.AddText("Document 1");
builder.SaveFile("docx", "document1.docx");
builder.CloseFile();

builder.CreateFile("xlsx");
var oWorksheet = Api.GetActiveSheet();
oWorksheet.GetRange("A1").SetValue("Spreadsheet 1");
builder.SaveFile("xlsx", "spreadsheet1.xlsx");
builder.CloseFile();

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js"
  }'

响应：

{
  "key": "af86C7e71Ca8",
  "urls": {
    "document1.docx": "https://documentserver/document1.docx",
    "spreadsheet1.xlsx": "https://documentserver/spreadsheet1.xlsx"
  },
  "end": true
}

文档比较

您可以比较两个文档并生成包含修订记录的结果文件。脚本使用 OpenTmpFile 打开第二个文档进行比较：

builderJS.OpenFile("https://example.com/file1.docx");
const file = builderJS.OpenTmpFile("https://example.com/file2.docx");
AscCommonWord.CompareDocuments(Api, file);
file.Close();
builderJS.SaveFile("docx", "Result.docx");
builderJS.CloseFile();

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/compare.js"
  }'

响应：

{
  "key": "Khirz6zTPdfd7",
  "urls": {
    "Result.docx": "https://documentserver/Result.docx"
  },
  "end": true
}

有关文档比较的更多详细信息，请参阅文档比较。

以文件形式发送脚本

从 10.0 版本开始，可以直接在请求中发送 .js 脚本文件，而不是其 URL。脚本通过 multipart/form-data 格式的 POST 请求发送到 https://documentserver/docbuilder/from-file 地址。

部分	类型	是否必填	描述
file	file	必填	.js 脚本文件。只能发送一个文件。文件大小受服务器设置 FileConverter.converter.maxDownloadBytes 限制。超出限制的文件将被拒绝，并返回 HTTP 413 状态码。仅在通过 key 检查异步请求状态时可以省略该文件。
params	string	必填	JSON 对象形式的请求参数：argument、async 和 key。不使用 url 参数。如果参数通过令牌发送，则可以省略 params 部分。
token	string	非必填	包含请求参数的令牌。令牌也可以作为 params 部分的 token 字段发送，或通过 Authorization 标头发送。启用令牌验证后，参数仅从令牌中获取。令牌的有效负载必须包含值为 docbuilder 的 operation 字段，且不得包含 url 字段。

响应与发送到 /docbuilder 地址的请求相同。要检查异步请求的状态，请发送带有返回的 key 值的 params 部分，不含 file 部分。

curl -X POST "https://documentserver/docbuilder/from-file" \
  -F 'params={"async":false}' \
  -F 'file=@script.js'

响应：

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

可能的错误代码及其描述

错误代码	描述
-1	未知错误。
-2	生成超时错误。
-3	文档生成错误。
-4	下载要生成的文档文件时出错。
-6	访问文档生成结果数据库时出错。
-8	令牌无效。