跳到主要内容

文档生成器 API

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

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

请求参数及其说明​

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

参数类型示例描述
endbooleantrue定义文档生成是否完成。当值为 false 时，任务仍在处理中，响应中不包含 urls 参数。当值为 true 时，任务已完成，urls 参数将出现在响应中。
errorinteger-8定义文档生成过程中发生的错误。可能的错误代码可在下方找到。
keystringaf86C7e71Ca8定义文档生成任务的唯一标识符。如果请求中提供了 key 参数，则返回相同的值。如果在第一个异步请求中未提供 key 参数，则由文档生成器服务生成新的 key。请在所有后续轮询请求中使用此值。
urlsobject{"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, null);
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
}

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

可能的错误代码及其描述​

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