场景库 API
场景库保存业务场景名称、定义和有序分类路径,供知识图谱与 Wiki 组织使用。
资源与基础路径
Base URL 使用实例 endpoint 的 /v1,资源包括场景、分类与导入预览。场景包含名称、定义、有序分类路径与 revision;分类知识绑定不继承父分类,删除分类前需要影响预览 token。修改成功后读取新 revision,HTTP 201 仅说明保存,不表示后续知识索引已构建。
认证与权限
scenarios.read 允许读取和预览;scenarios.write 用于创建、编辑、导入与删除。Header 携带项目身份与项目 Key,不能把 Console 组织身份替代成其他项目 Key。本文只覆盖项目范围。
端点清单
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
GET /scenarios | scenarios.read | scenarios.list |
POST /scenarios | scenarios.write | scenarios.create |
GET /scenarios/categories | scenarios.read | scenarios.listCategories |
POST /scenarios/categories | scenarios.write | scenarios.createCategory |
DELETE /scenarios/categories/{categoryId} | scenarios.write | scenarios.deleteCategory |
GET /scenarios/categories/{categoryId}/deletion | scenarios.read | scenarios.getCategoryDeletionImpact |
PATCH /scenarios/categories/{categoryId}/knowledge-binding | scenarios.write | scenarios.updateKnowledgeBinding |
PATCH /scenarios/categories/{categoryId}/name | scenarios.write | scenarios.renameCategory |
POST /scenarios/import | scenarios.write | scenarios.import |
POST /scenarios/import/parse | scenarios.read | scenarios.parseImport |
POST /scenarios/import/preview | scenarios.read | scenarios.previewImport |
GET /scenarios/{scenarioId} | scenarios.read | scenarios.get |
PATCH /scenarios/{scenarioId} | scenarios.write | scenarios.update |
DELETE /scenarios/{scenarioId} | scenarios.write | scenarios.delete |
请求与响应
GET /scenarios
list
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
limit | query | 否 | integer | format=int32; default=25 | 分页大小。 |
offset | query | 否 | integer | format=int32; default=0 | 分页偏移量。 |
search | query | 否 | string | default="" | 名称包含的文本。 |
categories | query | 否 | array[string] | default=[] | 分类路径。 |
includeDescendants | query | 否 | boolean | default=true | 是否包含下级分类中的场景。 |
成功响应:HTTP 200 — scenarioList.
返回字段:total (integer), scenarios (array).
POST /scenarios
create
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
scenarioId | body | 否 | string | default="unique()" | 场景 ID。 |
categories | body | 是 | array[string] | — | 有序分类路径。 |
name | body | 是 | string | — | 场景名称。 |
definition | body | 否 | string | default="" | 场景定义。 |
成功响应:HTTP 201 — scenario.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
GET /scenarios/categories
listCategories
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
limit | query | 否 | integer | format=int32; default=100 | 分页大小。 |
offset | query | 否 | integer | format=int32; default=0 | 分页偏移量。 |
成功响应:HTTP 200 — scenarioCategoryList.
返回字段:total (integer), categories (array).
POST /scenarios/categories
createCategory
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
categories | body | 是 | array[string] | — | 有序分类路径。 |
成功响应:HTTP 201 — scenarioCategory.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
DELETE /scenarios/categories/{categoryId}
deleteCategory
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
categoryId | path | 是 | string | — | 分类 ID。 |
token | body | 是 | string | — | 确认删除影响后取得的令牌。 |
成功响应:HTTP 204 — No content.
GET /scenarios/categories/{categoryId}/deletion
getCategoryDeletionImpact
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
categoryId | path | 是 | string | — | 分类 ID。 |
成功响应:HTTP 200 — scenarioCategoryImpact.
返回字段:token (string), categories (array), scenarios (array).
PATCH /scenarios/categories/{categoryId}/knowledge-binding
updateKnowledgeBinding
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
categoryId | path | 是 | string | — | 分类 ID。 |
revision | body | 是 | integer | format=int32 | 预期的绑定修订号。 |
knowledgeBaseId | body | 否 | string | default="" | 知识库 ID;留空可解除绑定。 |
knowledgeTagPath | body | 否 | string | default="" | 完整标签目录路径;留空可解除绑定。 |
knowledgeBindings | body | 否 | array[array] | — | 知识目录绑定列表;空列表解除全部绑定。 |
成功响应:HTTP 200 — scenarioCategory.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
PATCH /scenarios/categories/{categoryId}/name
renameCategory
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
categoryId | path | 是 | string | — | 分类 ID。 |
revision | body | 是 | integer | format=int32 | 预期的分类修订号。 |
name | body | 是 | string | — | 新的分类名称。 |
成功响应:HTTP 200 — scenarioCategory.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
POST /scenarios/import
import
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
entries | body | 是 | array[object] | — | 需要原子导入的场景。 |
conflictPolicy | body | 否 | string | enum=error, skip, overwrite; default="error" | 路径和名称已存在时的处理方式:拒绝、跳过或覆盖;内容未变化的覆盖会被跳过。 |
成功响应:HTTP 201 — scenarioImport.
返回字段:total (integer), scenarios (array), created (integer), updated (integer), skipped (integer).
POST /scenarios/import/parse
parseImport
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
file | formData | 是 | file | — | CSV、XLS 或 XLSX 场景文件;解析过程不会写入存储或场景。 |
成功响应:HTTP 200 — scenarioImportFile.
返回字段:sheets (array).
POST /scenarios/import/preview
previewImport
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
entries | body | 是 | array[object] | — | 仅供预览、不会写入的场景。 |
conflictPolicy | body | 否 | string | enum=skip, overwrite; default="skip" | 预览跳过或覆盖已有场景的结果;提交导入时会重新检查冲突。 |
成功响应:HTTP 200 — scenarioImportPreview.
返回字段:total (integer), entries (array), created (integer), updated (integer), skipped (integer).
GET /scenarios/{scenarioId}
get
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
scenarioId | path | 是 | string | — | 场景 ID。 |
成功响应:HTTP 200 — scenario.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
PATCH /scenarios/{scenarioId}
update
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
scenarioId | path | 是 | string | — | 场景 ID。 |
revision | body | 是 | integer | format=int32 | 预期修订号。 |
categories | body | 否 | array[string] | — | 有序分类路径。 |
name | body | 否 | string | — | 场景名称。 |
definition | body | 否 | string | — | 场景定义。 |
成功响应:HTTP 200 — scenario.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
DELETE /scenarios/{scenarioId}
delete
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
scenarioId | path | 是 | string | — | 场景 ID。 |
revision | body | 是 | integer | format=int32 | 预期修订号。 |
成功响应:HTTP 204 — No content.
错误与边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。
与 Server SDK 的对应
上述端点表中的 scenarios 对应 Node Scenarios 服务;Python 使用 snake_case,Java/Go 的签名与同版本制品分别核对,不从 Node 参数位置推断。下面请求展示列表读取,环境变量由服务端注入。
(
set +x
set -o pipefail
: "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}" | curl --disable --header @- --fail-with-body --get "$AGENTBASE_ENDPOINT/scenarios" \
-H "X-Appwrite-Project: $AGENTBASE_PROJECT_ID" \
--data-urlencode "limit=25" --data-urlencode "offset=0"
)导入 entries 实际为对象数组,每项包含 categories/name/definition。生成 spec 的 array[array] 与 Node TypeScript 的 any[][] 类型过窄;本页按服务端校验器列出真实 JSON 形状,JavaScript 示例直接复用 parseImport 返回的条目。TypeScript 接入需隔离这一类型差异,不把类型断言当作请求已通过验证。