HTTP 接口文档

作者：周五
更新于：2023.08.28

本文主要介绍了分形三维的 HTTP 接口，包括上传、获取文件，图纸格式转换，生成缩略图，评论和实时评论，并且对接口限流策略、鉴权和审计等内容也进行了介绍。

上传、获取文件

上传和获取文件的功能使用户能够方便地存储和访问其文件。

上传文件

用户可以上传所需的文件到平台中。确保你上传的文件格式是平台所支持的，而且大小不超过限制。

接口：`POST /api/files`

请求参数：

Query 参数：

file_name：上传文件的文件名，必填
file_size：文件大小，单位为字节，必填，最大值为 4*1024*1024*1024 字节
file_retention_days：文件保留时间（天），默认为 -1 表示永久保留，最大值 365

Body 是一个 application/octet-stream 类型的二进制文件流，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含文件 ID 的 JSON 对象

{
  "file_id": "分形三维记录的文件 ID"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

获取文件

已上传的文件可以随时从平台上下载或访问。只需通过以下获取文件的接口即可。

接口：`GET /api/files`

请求参数：

Query 参数：

file_id：文件 ID，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含文件 ID 的 JSON 对象

{
  "file_id": "文件 ID",
  "file_name": "文件名",
  "size": "文件大小，整数",
  "signed_url": "已签名的文件下载地址"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

例如，当请求的文件不存在时，返回的 HTTP 状态码为 404，错误信息为：

{
  "message": "file not found"
}

图纸格式转换

一些 CAD 文件格式需要转换为 E3DX / E2DX 文件，以在 Web 端显示。

对于 SolidWorks / UG / CATIA 等复杂格式文件的渲染，请参考复杂格式文件显示 demo
参考支持格式清单可以更好地帮助你了解你所需要渲染的文件是否可以使用分形三维来渲染以及判断文件是否为复杂格式

请求转换

请求将文件转换为 E3DX / E2DX 格式，以在 Web 端显示。

接口：`POST /api/converts`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，必填

{
  "url": "可以访问到的文件 URL，如果没有通过上传文件获得 file_id，可以直接在这里传入 URL 进行转换，url 和 file_id 的形式可以二选一",
  "file_id": "传入上传接口返回的 file_id，url 和 file_id 的形式可以二选一",
  "file_name": "文件名，必填",
  "target_format": "如果是 3D 图纸，则传入 e3dx，如果是 2D 图纸，则传入 e2dx，必填",
  "webhook_url": "转换完成后的 WebHook 回调地址，会将转换结果以 POST 请求发送到该地址，可选"
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含转换 ID 的 JSON 对象

{
  "transaction_id": "分形三维记录的转换 ID"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

获取转换结果文件

获取转换结果文件，如果转换成功，会返回转换结果文件的 URL。

接口：`GET /api/converts/result_file`

请求参数：

Query 参数：

transaction_id：转换 ID，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含转换结果文件的 JSON 对象

{
  "url": "转换结果的文件 URL，当转换成功时返回",
  "status": "文件转换的状态，Pending、Succeeded、Failed"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "error": {
    "message": "返回对应的错误信息"
  }
}

生成缩略图

如果想生成图纸的缩略图，可以通过以下接口来实现。目前仅支持 3D 图纸的缩略图生成。

请求缩略图

请求生成 3D 图纸的缩略图。

接口：`POST /api/thumbnail`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，必填

{
  "url": "可以访问到的文件 URL，如果没有通过上传文件获得 file_id，可以直接在这里传入 URL 进行转换，url 和 file_id 的形式可以二选一",
  "file_id": "传入上传接口返回的 file_id，url 和 file_id 的形式可以二选一",
  "file_name": "文件名，必填",
  "width": "整数，缩略图的宽度，单位为像素，必填",
  "height": "整数，缩略图的高度，单位为像素，必填",
  "webhook_url": "缩略图生成完成后的 WebHook 回调地址，会将缩略图生成结果以 POST 请求发送到该地址，可选"
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含缩略图生成 ID 的 JSON 对象

{
  "transaction_id": "分形三维记录的缩略图生成 ID"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "error": {
    "message": "返回对应的错误信息"
  }
}

获取缩略图

获取缩略图，如果缩略图生成成功，会返回缩略图的 URL。

接口：`GET /api/thumbnail/result_file`

请求参数：

Query 参数：

transaction_id：缩略图生成 ID，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含缩略图的 JSON 对象

{
  "url": "缩略图的文件 URL，当缩略图生成成功时返回",
  "status": "缩略图生成的状态，Pending、Succeeded、Failed"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "error": {
    "message": "返回对应的错误信息"
  }
}

评论和实时评论

分形三维提供了评论和实时评论功能，可以让用户在 Web 端对图纸进行评论。

创建评论资源

创建评论资源，用于唯一标识一个被评论的实体，并且存储针对该实体的评论内容。

接口：`POST /api/resources`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，内容是任意 metadata，例如可以存储原始 file_url，也可以是其他 metadata

{
  "file_url": "文件的 URL"
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含资源 ID 的 JSON 对象

{
  "resource_id": "分形三维记录的资源 ID"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

创建评论

在创建完评论资源后，可以通过以下接口创建评论。

接口：`POST /api/comments`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，必填

{
  "resource_id": "评论资源 ID，必填",
  "reply_to": "回复的评论 ID，可选",
  "info": {
    "message": "评论的内容，必填",
    "extra": "额外的信息，可以是任意 JSON 对象，可选"
  }
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含评论 ID 的 JSON 对象

{
  "comment_id": "分形三维记录的评论 ID"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

删除评论

如果想要删除评论，可以通过以下接口来实现。

接口：`DELETE /api/comments`

请求参数：

comment_id：评论 ID，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回 "Ok"

{
  "message": "Ok"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

获取评论列表

获取评论列表，可以通过以下接口来实现。

接口：`GET /api/comments`

请求参数：

Query 参数：

resource_id：评论资源 ID，必填

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含评论列表的 JSON 对象

{
  "comments": [
    {
      "comment_id": "评论 ID",
      "resource_id": "评论资源 ID",
      "reply_to": "回复的评论 ID",
      "info": {
        "message": "评论的内容",
        "extra": "额外的信息，可以是任意 JSON 对象"
      },
      "created_at": "评论创建时间"
    }
  ]
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

实时订阅评论

实时订阅评论依赖于 WebSocket 协议，分形三维的实时评论功能实现了 “房间(Room)” 这一概念，用户可以通过加入聊天室来实现实时订阅及发送评论。

加入房间接口：`POST /api/rooms`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，必填

{
  "room_id": "房间 ID，传入分形三维评论资源 ID(resource_id)，必填"
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回包含房间用户 ID 的 JSON 对象

{
  "user_id": "此次加入房间的临时用户 ID，可以理解为 session_id"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

离开房间接口：`DELETE /api/rooms`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，必填

{
  "room_id": "房间 ID，传入分形三维评论资源 ID(resource_id)，必填",
  "user_id": "房间用户 ID，传入加入房间接口返回的 user_id，必填"
}

返回值：

请求成功时 HTTP 状态码为 200，并且返回 "Ok"

{
  "message": "Ok"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

WebSocket 接口：`/api/ws`

订阅评论 Message:

{
  "endpoint": "/subscribe",
  "user": "加入房间接口返回的 user_id",
  "body": {
    "room_id": "需要订阅的房间 ID"
  }
}

发布评论 Message：

{
  "endpoint": "/publish",
  "user": "加入房间接口返回的 user_id",
  "body": {
    "room_id": "需要发布消息的房间 ID",
    "info": "发送的消息，可以是任意 JSON 对象"
  }
}

接口限流、鉴权和审计

为了确保平台的稳定性和安全性，我们提供了接口限流、鉴权和审计功能。下面将对这些功能进行介绍。

接口限流策略

为了防止过度使用，每个接口都有一个使用频率的上限。分形三维使用 “令牌桶” 算法对接口调用进行限流，默认的接口限流策略如下：

对于 匿名调用者，分形三维会记录调用者的 IP 地址，令牌桶的大小为 100，每秒钟恢复 10 个令牌，即每秒钟最多可以调用 10 次接口。

对于使用 AccessToken 的调用，分形三维会记录调用者的 AccessToken，令牌桶的大小为 500，每秒钟恢复 50 个令牌，即每秒钟最多可以调用 50 次接口。

对于使用 API Key 的调用，分形三维会记录调用者的 API Key，令牌桶的大小为 200，每秒钟恢复 20 个令牌，即每秒钟最多可以调用 20 次接口。

当令牌桶中的令牌数量为 0 时，接口调用会被拒绝，HTTP 状态码为 429，错误信息为 too many requests。

{
  "message": "too many requests"
}

如何通过 HTTP Response Header 获取接口限流信息

为了帮助开发者决定何时以编程方式重试 API 调用，在 HTTP 响应中，包含了解释限流的响应标头。

X-RateLimit-Limit：每秒钟最多可以调用的次数
X-RateLimit-Remaining：当前令牌桶中剩余的令牌数量
X-RateLimit-Reset：令牌桶恢复满令牌所需的时间，单位为秒

目前接口限流策略是固定的，未来会根据用户用量进行调整，如果你有更好的建议及特殊需求，欢迎联系我们。

API Key 和 AccessToken 如何使用？

分形三维使用 API Key 和 AccessToken 来实现鉴权，这两者有不同的使用场景：

API Key：
- 应用级别鉴权：API Key 通常用于鉴别整个应用或服务。当开发者注册其应用或服务后，系统会为他们提供一个唯一的 API Key。这样，分形三维就可以知道是哪个应用正在请求访问。
- 长期有效：API Key 通常具有长时间的有效期。一般用于后端服务向分形三维服务发送请求。
- 所有权限：API Key 具有用户资源的所有权限。
AccessToken：
- 短时有效：AccessToken 通常具有短时间的有效期。一旦过期，需要用户重新认证或通过刷新令牌来获取新的 AccessToken。
- 可细化权限：AccessToken 可以承载更细粒度的权限或作用域信息，允许对用户的操作进行更精细的控制，具体的权限请参阅权限 Scope 一览表。

在调用接口时，可以通过在 HTTP Header 中传入 API Key 或 AccessToken 来进行鉴权，具体的传入方式如下：

Authorization: Bearer <API Key 或 AccessToken>

如果你在使用分形三维的 API 时遇到了鉴权问题，或者有更好的建议及特殊需求，欢迎联系我们。

生成 AccessToken

可以调用以下接口生成 AccessToken，AccessToken 的有效期为 24 小时。

接口：`POST /api/users/access-token`

请求参数：

Body 是一个 application/json 类型的 JSON 对象，传入了 permissions 数组，具体可参考权限 Scope 一览表。

{
  "permissions": [
    {
      "resource": "分形三维可用资源组，例如 cabin、turbine、hub、signalman",
      "operation": "权限，read 或 write"
    }
  ]
}

返回值：

请求成功时，HTTP 状态码为 200，并且返回包含 AccessToken 的 JSON 对象

{
  "access_token": "有效的 AccessToken"
}

请求失败时会根据错误类型返回不同的 HTTP 状态码和错误信息

{
  "message": "返回对应的错误信息"
}

权限 Scope 一览表

查看所有可用的权限范围，并了解它们的用途。

Scope 名称	说明
`ReadFile`	读取文件
`WriteFile`	写入文件
`ReadTransaction`	读取转换结果
`WriteTransaction`	写入转换结果
`ReadUser`	读取用户
`WriteUser`	写入用户
`ReadChatroom`	读取聊天室
`WriteChatroom`	写入聊天室

资源组和操作的对应关系如下：

资源组	操作	Scope
`Cabin`	`Read`	`ReadFile`
`Cabin`	`Write`	`WriteFile`
`Turbine`	`Read`	`ReadTransaction`
`Turbine`	`Write`	`WriteTransaction`
`Hub`	`Read`	`ReadUser`
`Hub`	`Write`	`WriteUser`
`Signalman`	`Read`	`ReadChatroom`
`Signalman`	`Write`	`WriteChatroom`

目前分形三维正在逐步重构鉴权系统，如果你有更好的建议及特殊需求，欢迎联系我们。

接口操作审计日志

为了增加透明性，所有执行成功的接口调用都会被记录在审计日志中。目前没有提供查询审计日志的接口，如果你需要查询审计日志，请联系我们。

未来会在分形三维的控制台中提供查询审计日志的功能。

接口错误一览表

查看所有可能的错误类型，并了解它们的含义。

错误类型	HTTP 状态码	说明
`InvalidParameter`	400	请求参数错误
`PermissionDenied`	403	权限不足
`NotSupported`	403	不支持的操作
`NotFound`	404	资源不存在
`InstanceNotInitialized`	428	实例未初始化
`RequestRateLimited`	429	请求过于频繁
`InternalServerError`	500	服务器内部错误

一般来说，如果你在使用分形三维的 API 时遇到了错误，可以通过 HTTP Response Body 中的 message 字段来查看错误信息。

如果你在使用分形三维的过程中遇到了问题，或者有更好的建议及特殊需求，欢迎通过扫描右侧的 遇到问题？联系我们 二维码，加入分形三维开发者社群。

HTTP 接口文档

上传、获取文件

上传文件

接口：POST /api/files

请求参数：

返回值：

获取文件

接口：GET /api/files

请求参数：

返回值：

图纸格式转换

请求转换

接口：POST /api/converts

请求参数：

返回值：

获取转换结果文件

接口：GET /api/converts/result_file

请求参数：

返回值：

生成缩略图

请求缩略图

接口：POST /api/thumbnail

请求参数：

返回值：

获取缩略图

接口：GET /api/thumbnail/result_file

请求参数：

返回值：

评论和实时评论

创建评论资源

接口：POST /api/resources

请求参数：

返回值：

创建评论

接口：POST /api/comments

请求参数：

返回值：

删除评论

接口：DELETE /api/comments

请求参数：

返回值：

获取评论列表

接口：GET /api/comments

请求参数：

返回值：

实时订阅评论

加入房间接口：POST /api/rooms

请求参数：

返回值：

离开房间接口：DELETE /api/rooms

请求参数：

返回值：

WebSocket 接口：/api/ws

接口限流、鉴权和审计

接口限流策略

如何通过 HTTP Response Header 获取接口限流信息

API Key 和 AccessToken 如何使用？

生成 AccessToken

接口：POST /api/users/access-token

请求参数：

返回值：

权限 Scope 一览表

接口操作审计日志

接口错误一览表

接口：`POST /api/files`

接口：`GET /api/files`

接口：`POST /api/converts`

接口：`GET /api/converts/result_file`

接口：`POST /api/thumbnail`

接口：`GET /api/thumbnail/result_file`

接口：`POST /api/resources`

接口：`POST /api/comments`

接口：`DELETE /api/comments`

接口：`GET /api/comments`

加入房间接口：`POST /api/rooms`

离开房间接口：`DELETE /api/rooms`

WebSocket 接口：`/api/ws`

接口：`POST /api/users/access-token`