跳到主要内容

文件上传请求

文档转换服务可以转换随请求一起发送的文件，因此 ONLYOFFICE 文档无需从文档存储服务下载该文件。文件通过 multipart/form-data 格式的 POST 请求发送到 https://documentserver/converter/from-file 地址，其中 documentserver 是安装了 ONLYOFFICE 文档的服务器的名称。

信息

此端点从 ONLYOFFICE 文档 10.0 版本开始提供。它与请求端点一样，可通过服务器设置 services.CoAuthoring.server.convertServiceEnable 关闭。

请求部分​

部分类型是否必填描述
filefile必填要转换的文件。只能发送一个文件。文件大小受服务器设置 FileConverter.converter.maxDownloadBytes 限制。超出限制的文件将被拒绝，并返回 HTTP 413 状态码。仅在检查异步转换状态时可以省略该文件。
paramsstring必填JSON 对象形式的转换参数。它接受与发送到 /converter 地址的请求相同的参数，但不使用 url。如果未指定 filetype，则从上传文件名的扩展名中获取。如果参数通过令牌发送，则可以省略 params 部分。
tokenstring非必填包含转换参数的令牌。令牌也可以作为 params 部分的 token 字段发送，或通过 Authorization 标头发送。

包含任何其他部分的请求均无效，并返回 -7 错误。

响应​

响应取决于转换结果：

  • 转换完成后，响应正文就是转换后的文件本身。Content-Disposition 标头中的文件名由 title 参数或上传的文件名加上输出格式的扩展名构成。
  • 当异步转换仍在进行时，将以 JSON 格式返回响应，其中 endConvert 参数为 false。
  • 发生错误时，将以 JSON 格式返回包含 error 参数的响应。可能的值列在错误代码页面中。

请求示例​

将 txt 转换为 docx​

curl -f -X POST "https://documentserver/converter/from-file" \
  -F 'params={"filetype":"txt","outputtype":"docx","title":"Example Document Title.txt"}' \
  -F 'file=@example.txt' \
  -o "Example Document Title.docx"

转换后的 docx 文件保存为 Example Document Title.docx。

异步请求​

要异步转换大文件，请将 async 参数设置为 true，并指定 key 参数：

curl -X POST "https://documentserver/converter/from-file?shardkey=Khirz6zTPdfd7" \
  -F 'params={"async":true,"key":"Khirz6zTPdfd7","outputtype":"pdf"}' \
  -F 'file=@example.docx'

转换进行期间，将以 JSON 格式返回响应：

{
  "endConvert": false,
  "percent": 0
}

要检查状态，请再次发送带有相同 params 部分但不含 file 部分的请求。转换任务由 key 值与其他参数共同标识，因此这些参数不得更改。转换完成后，响应正文就是转换后的文件。

curl -X POST "https://documentserver/converter/from-file?shardkey=Khirz6zTPdfd7" \
  -F 'params={"async":true,"key":"Khirz6zTPdfd7","outputtype":"pdf"}' \
  -o "example.pdf"
备注

如果没有 key 参数，转换任务将由文件内容标识，不重新发送文件就无法检查其状态。在分片集群中，请将 shardkey 参数添加到查询字符串中，否则请求将以同步方式处理。

带令牌的请求​

如果对传入请求启用了令牌验证，则转换参数仅从令牌中获取。令牌的有效负载必须包含值为 converter 的 operation 字段，且不得包含 url 字段。

有效负载示例：

{
  "filetype": "docx",
  "outputtype": "pdf",
  "title": "Example Document Title.docx",
  "operation": "converter"
}

请求：

curl -f -X POST "https://documentserver/converter/from-file" \
  -F 'token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJvdXRwdXR0eXBlIjoicGRmIiwidGl0bGUiOiJFeGFtcGxlIERvY3VtZW50IFRpdGxlLmRvY3giLCJvcGVyYXRpb24iOiJjb252ZXJ0ZXIifQ.d2nBRLobbqCdOmpmtm41cuECtNcIvMwJmLMnNrcNuKg' \
  -F 'file=@example.docx' \
  -o "Example Document Title.pdf"