跳转到内容
Vibma

端点

部分 Vibma 工具是端点工具 — 它们将多种操作（create、get、list、update、delete）整合到一个工具中，通过 method 参数进行分发，类似于 REST API。

为什么使用端点？

Section titled “为什么使用端点？”

与其使用 create_style、get_style、list_styles、update_style、delete_style 等多个独立工具，不如用一个 styles 端点来处理所有操作。这样可以减少工具总数，并将相关操作组织在一起。

通用契约

Section titled “通用契约”

每个端点都遵循相同的模式：

Method输入输出
create{items: [{...}]}{results: [{id}, ...]}
get{id, fields?}资源对象（字段过滤后）
list{fields?, offset?, limit?}{totalCount, returned, offset, limit, items}
update{items: [{id, ...}]}{results: ["ok", ...]}
delete{id} 或 {items: [{id}]}"ok" 或 {results: ["ok", ...]}

并非每个端点都支持全部五种方法。请查看各工具的 method 枚举以了解可用操作。

共享参数

Section titled “共享参数”

以下参数会根据端点支持的方法自动可用：

  • method（必填）— 要执行的操作
  • id — 资源 ID，用于 get 和 delete
  • fields — get 和 list 的属性白名单。标识字段（id、name、type）始终包含在内。传入 ["*"] 可返回所有字段。
  • offset / limit — list 的分页参数（默认 limit: 100）
  • items — 批量操作（create、update、delete）的对象数组

批量响应

Section titled “批量响应”

create、update 和 delete 返回一个 results 数组，每个条目与输入的 items 一一对应。每个条目为 "ok"、包含结果数据的对象（如 create 返回 {id: "..."}），或失败时的 {error: "message"}。这允许部分成功 — 一些项目可以成功，而另一些失败。

{
  "results": [
    {"id": "S:abc123"},
    {"error": "Name already exists: Primary"}
  ]
}

字段过滤

Section titled “字段过滤”

在 get 和 list 中使用 fields 来减少响应大小。不使用 fields 时，list 返回存根（仅标识字段），get 返回完整详情。

{"method": "list", "fields": ["description", "valuesByMode"]}

访问层级

Section titled “访问层级”

端点中的每个方法都受访问层级的限制：

Method所需层级
get, listread（始终可用）
create--create
update, delete--edit

部分端点定义了自定义的方法层级。例如，variable_collections 将 add_mode 映射到 create，将 rename_mode / remove_mode 映射到 edit。

端点工具

Section titled “端点工具”

以下工具使用端点模式：