SuperAPI AI 工具集

speckle-core-api

编程与开发

查看项目

更新于 10-16 08:50

技能介绍

用途:连接 Speckle Server、完成认证,并理解其 GraphQL 与 REST API 接口,避免新旧术语混淆。

主要能力:

  • API 分层:GraphQL(HTTP POST,https://<server>/graphql)负责元数据 CRUD 与订阅;REST 负责对象上传下载,包括 GET /objects/:projectId/:objectId(含子对象,gzip 流)、GET /objects/:projectId/:objectId/single(单对象)、POST /objects/:projectId(上传)、POST /auth/token(换取或刷新令牌)。
  • 术语映射:Stream→Project、Branch→Model、Commit→Version、StreamCollaborator→ProjectCollaborator,新代码应使用当前术语。
  • 认证:请求头 Authorization: Bearer <YOUR_TOKEN>,适用于 PAT 与 OAuth2,GraphQL 与 REST 通用。服务端脚本/CLI/CI 用 PAT;浏览器/桌面应用用 OAuth2 + challenge 流程;Automate 函数由运行时注入令牌。
  • 权限范围:streams:read/write、profile:read/email/write/delete、tokens:read/write、users:read、apps:read、server:setup。
  • 服务器发现:先查询 serverInfo(无需认证)获取版本、对象大小限制、scopes、authStrategies、workspaces 等。
  • 分页与限流:所有集合使用游标分页,必须指定 limit,cursor 为 null 表示无更多页;429 需读取 Retry-After 并实现指数退避。
  • 错误处理:GraphQL 错误码 FORBIDDEN、UNAUTHENTICATED、NOT_FOUND、BAD_USER_INPUT;REST 状态码 401/403/404/413/429。
  • Webhook 触发器仍使用旧内部名(如 commit_create、branch_update),UI 显示名不同。

使用方式:先查询 serverInfo 确认能力,再按场景选择 PAT 或 OAuth2,GraphQL 处理元数据、REST 处理对象数据,遵循标准发送/接收流程。

限制:不得在新代码中使用旧查询;不得在浏览器端嵌入 PAT;不得硬编码服务器地址;大对象树应使用 REST 而非 project.object.data;不得忽略 429 与分页。Server 2.x 与 3.x 在旧查询、Workspaces 上存在差异,需查询 serverInfo.version 判断。具体代码示例见资料引用的 references 文件,本资料未提供完整示例。