API 接口文档

概述

本文描述 Umo Office Convert 服务提供的 API 接口。该服务主要用于将各种 Office 文档和 PDF 文档-转换为 Umo Office Viewer 可查看的格式。

基础信息

• 基础URL: http://localhost:1236（默认端口，可在环境变量中配置）
• 在非生产环境下，可以通过 /openapi 路径访问 Swagger UI 接口文档

接口列表

1. 检查服务状态

检查服务是否正常运行。

• URL: /
• 方法: GET
• 描述: 返回服务是否正在运行的信息，如果无法访问该路由，则代表服务未启动或服务异常。

响应示例:

{
  "code": 200,
  "success": true,
  "data": "Umo Office Convert 服务已启动"
}

2. 上传文件进行转换

通过表单上传文件进行转换。

• URL: /convert/upload
• 方法: POST
• Content-Type: multipart/form-data
• 参数:
  • file: 要转换的文件（必填）

响应:

• 成功时返回转换后的文件流
• 失败时返回 JSON 格式的错误信息

响应头:

• X-Task-Id: 转换任务 ID
• X-Document-Name: 原始文档名称
• X-From-Cache: 是否从缓存中获取的文件
• Content-Disposition: 文件下载信息
• Content-Type: 文件类型
• Content-Length: 文件大小

错误响应示例:

{
  "code": 500,
  "success": false,
  "message": "文档转换，错误原因: 转换过程中发生了异常"
}

3. 通过 JSON 数据进行转换

通过 JSON 数据提交文件信息进行转换。

• URL: /convert
• 方法: POST
• Content-Type: application/json
• 请求体:

  {
    "path": "/path/to/测试文档.docx",
    "filename": "测试文档.docx"
  }

响应:

• 成功时返回转换后的文件流
• 失败时返回 JSON 格式的错误信息

4. 通过 URL 进行转换

通过 URL 参数提交文件信息进行转换。

• URL: /convert
• 方法: GET
• 参数:
  • url: 要转换的文件网络地址（必填，需 URL 编码）
  • filename: 原始文档的文件名称（必填，需 URL 编码）

响应:

• 成功时返回转换后的文件流
• 失败时返回 JSON 格式的错误信息

5. 根据任务 ID 获取文件

根据转换任务 ID 获取转换后的文件或原始文件。

• URL: /convert/{taskId}
• 方法: GET
• 参数:
  • taskId: 转换任务 ID（路径参数）
  • target: 获取的文件类型，可选值为 converted（转换后的文件）或 original（原始文件），默认为 converted

响应:

• 成功时返回请求的文件流
• 失败时返回 JSON 格式的错误信息

支持的文件格式

服务支持转换多种 Office 文档格式，所支持的格式见：支持转换的文件格式。

错误处理

所有接口在发生错误时都会返回统一格式的 JSON 响应：

{
  "code": 状态码,
  "success": false,
  "message": "错误信息"
}

常见错误状态码：

• 400: 请求参数错误
• 403: 访问被拒绝（白名单限制）
• 404: 资源不存在
• 500: 服务器内部错误

Webhook 通知

服务支持通过 Webhook 接收文件转换完成的通知。可以在环境变量中配置 WEBHOOK_URL，详见：环境变量-Webhook 配置。