用途:在针对 Speckle Server API 编写 GraphQL 查询、变更或订阅时使用,帮助避免错误的分页模式、缺失的变量声明等问题。
主要能力:提供端点与认证约定、查询/变更/订阅示例、游标分页模式、集合字段差异、错误响应格式与常见错误码。
必要用法:请求一律使用 HTTP POST,JSON 体包含 query、variables 与可选 operationName;认证请求必须带 Authorization: Bearer <PERSONAL_ACCESS_TOKEN>,PAT 与 OAuth2 令牌均适用,仅 serverInfo 无需认证。分页字段必须显式指定 limit,使用 cursor + limit 的游标分页,cursor 为 null 表示无更多页。ObjectCollection 的子项字段是 objects 而非 items。变量需在操作签名中声明类型。术语使用 project、model、version,而非旧的 stream、branch、commit。
适用场景:查询当前用户与项目、模型、版本,执行项目/模型/版本/Webhook/API 令牌的变更,以及通过 WebSocket 订阅项目与模型更新。
限制:未提供具体收费、价格、平台或效果信息;object.children 上使用 query 或 orderBy 会触发昂贵 SQL 路径,需谨慎;apiTokenCreate 返回的令牌只能立即保存,无法再次获取。