GraphQL API
以 GraphQL 查询(Query)与变更(Mutation)协议访问 Agentbase 平台数据面:查询语法、权限判定、限流配额与 REST 数据模型保持严格一致,支持单次请求聚合多域资源读取与字段级投影裁剪。
服务与资源边界
GraphQL API 为项目内各核心业务域(账户与用户、团队、TablesDB / DocumentsDB 数据库、Storage 存储桶与文件、Functions 函数执行等)提供统一的图查询与变更入口。其核心边界如下:
协议与模型同构:GraphQL Schema 由平台根据当前项目的系统元数据及用户自定义表/集合结构动态映射生成,底层复用与 REST API 完全一致的 Service 层、Validator 校验器与 OceanBase 存储引擎(支持
Shared V2等表池模式)。单往返多资源聚合:在需要同时读取项目内多个关联资源(例如同时获取当前团队信息、工单表记录与存储桶元数据)或裁剪响应字段以降低带宽开销的场景下,可通过单次
POST /v1/graphql请求替代多次 REST 往返。不替代二进制流与长连接流:文件流式下载(
/storage/buckets/{bucketId}/files/{fileId}/download)、知识库原始文档流、以及 Agent Runtime 的 SSE 事件流(/v1/agent-runtime/runs/{runId}/events)不经由 GraphQL 承载,仍使用对应 REST / SSE 端点。HTTP 状态码与业务错误分离:遵循 GraphQL 规范,只要 HTTP 传输层与 JSON 解析成功,即使单个 resolver 发生权限拒绝或参数校验失败,HTTP 状态码仍返回
200 OK,具体异常封装在响应体的errors[]数组中。
资源与基础路径
Base URL:
https://appbuild-sit.oceanbase.com/v1(或您的私有化实例端点https://<your-endpoint>/v1)。路径前缀:
/graphql;无状态计算端点,不持久化 GraphQL 查询文档自身。核心请求/响应模型:
| 模型名称 | 方向 | 核心字段 | 说明 |
|---|---|---|---|
GraphQLRequest | 请求体 | query (string), variables (object), operationName (string) | 标准 GraphQL POST JSON 载荷,也支持 application/graphql 原始查询文本 |
GraphQLResponse | 响应体 | data (object | null), errors (GraphQLError[]) | 标准 GraphQL 响应信封;部分成功时 data 与 errors 可同时存在 |
GraphQLError | 错误项 | message (string), locations (array), path (array), extensions (object) | 单个字段解析或变更执行失败的定位信息与错误上下文 |
认证与权限
认证与请求头约定见 通用约定。
请求头矩阵
| 请求头 | 必填 | 取值示例 | 说明 |
|---|---|---|---|
X-Appwrite-Project | 是 | enterprise-ai-hub-210 | 目标项目 ID(如展示环境「企业智能客服与知识中台」项目) |
X-Appwrite-Key | 服务端必填 | <APPBASE_API_KEY> | 项目级 API Key,服务端调用时须包含 graphql 及被调资源对应 scope |
X-Appwrite-JWT | 客户端可选 | <USER_JWT_TOKEN> | 客户端以最终用户身份调用时传入的短时 JWT 令牌 |
X-Appwrite-Response-Format | 否 | 1.6.0 | 响应兼容格式版本头 |
Content-Type | 是 | application/json 或 application/graphql | JSON 载荷模式或纯 GraphQL 查询文本模式 |
Scope 与资源级权限判定
基础入口 Scope:API Key 必须首先具备
graphqlscope(否则入口直接拒绝并返回general_unauthorized_scope)。下游 Resolver 级联授权:GraphQL 引擎在执行每个頂层 Query 或 Mutation 字段时,会二次校验该字段映射的底层 REST 操作所需的 Scope(例如执行
teamsCreate需要teams.write,执行tablesCreateRow需要rows.write)。行级与文件级安全(Row / Document / File Security):当使用客户端 Session 或
X-Appwrite-JWT访问时,底层强制执行目标表/集合/存储桶的$permissions策略(详见 权限字符串文法);携带服务端X-Appwrite-Key时仅检查 API Key Scope。
端点总览
GraphQL 模块提供两个核心 HTTP POST 端点,分别服务于只读查询与状态变更(底层的执行管线共享同一 Schema 解析器,拆分为两个路径便于网关层按路径配置读写分离限流与审计策略):
| 能力分类 | 端点路径 | 幂等性 | 速率限制 | 典型应用场景 |
|---|---|---|---|---|
| 数据查询(Query) | POST /v1/graphql | 是(仅执行 query 操作时) | 60 次/分钟 | 聚合查询团队、用户、业务表记录(如客服工单 customer_tickets)及存储桶文件列表 |
| 状态变更(Mutation) | POST /v1/graphql/mutation | 否(取决于具体变更操作) | 60 次/分钟 | 创建团队、写入/更新业务表行记录、创建函数执行或更新用户偏好配置 |
端点清单
| 方法 + 路径 | Scope | 幂等性 | 用途 |
|---|---|---|---|
POST /graphql | graphql + 目标域读取 scope | 是 | 执行 GraphQL 查询(Query)操作 |
POST /graphql/mutation | graphql + 目标域写入 scope | 否 | 执行 GraphQL 变更(Mutation)操作 |
端点详解
查询与变更执行机制
解析与语法树校验(Parse & Validate):服务端接收
query字符串后解析为 AST,校验字段名称、参数类型及嵌套深度。默认最大查询嵌套深度(Max Query Depth)为10层,单次批量操作上限受项目配额约束,防止恶意循环嵌套查询耗尽 CPU。变量绑定(Variables Substitution):推荐将动态过滤条件(如项目内工单 ID
TK-20261022-001、分页queries数组)提取至variablesJSON 对象中传入,以便服务端复用已编译的查询计划并彻底避免字符串拼接注入风险。字段命名映射规则:
REST 响应中的系统元数据字段(以
$开头,如$id、CreatedAt、$updatedAt、$permissions、$databaseId、$tableId)在 GraphQL Schema 中因语法规范限制,统一映射为下划线前缀:_id、_createdAt、_updatedAt、_permissions、_databaseId、_tableId。嵌套 JSON 对象或无固定 Schema 的动态载荷字段(如行记录的
data字段、用户prefs)在 GraphQL 中序列化为 JSON 字符串返回,客户端解析后即可还原为结构化对象。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。
POST /v1/graphql
执行 GraphQL 查询:请求体为标准 GraphQL query / variables / operationName JSON 文档,Schema 覆盖各域 REST 的等价读取操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | GraphQL 查询文档字符串(如 query ListSupportTeams(...) { ... })。 |
variables | body | object | 否 | {} | 查询变量键值对对象,与 query 文档中的 $varName 变量声明严格对应。 |
operationName | body | string | 否 | null | 当 query 文档包含多个具名操作时,显式指定本次要执行的操作名称。 |
输出:返回 200 OK + 标准 GraphQL 响应对象:
| 字段 | 类型 | 说明 |
|---|---|---|
data | object | null | 按查询选择集(Selection Set)裁剪后的结构化结果对象;顶层执行完全失败时为 null |
errors | array | 可选错误列表;完全成功时省略该字段。每个元素包含 message、locations(line/column)与 path |
调用示例(聚合查询项目内团队列表与客服业务库信息):
curl -X POST "https://appbuild-sit.oceanbase.com/v1/graphql" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"operationName": "GetSupportWorkspaceOverview",
"query": "query GetSupportWorkspaceOverview($teamQueries: [String!], $bucketId: String!) { teamsList(queries: $teamQueries) { total teams { _id _createdAt name total } } storageGetBucket(bucketId: $bucketId) { _id name fileSecurity maximumFileSize enabled } }",
"variables": {
"teamQueries": ["limit(10)"],
"bucketId": "kb_enterprise_docs"
}
}'响应示例(200 OK):
{
"data": {
"teamsList": {
"total": 2,
"teams": [
{
"_id": "team_tier2_support",
"_createdAt": "2026-10-20T08:15:00.000+00:00",
"name": "二线分布式数据库专家组",
"total": 8
},
{
"_id": "team_ai_ops",
"_createdAt": "2026-10-21T03:40:00.000+00:00",
"name": "AI 网关与知识中台运维组",
"total": 5
}
]
},
"storageGetBucket": {
"_id": "kb_enterprise_docs",
"name": "企业知识库文档存储桶",
"fileSecurity": true,
"maximumFileSize": 52428800,
"enabled": true
}
}
}POST /v1/graphql/mutation
执行 GraphQL 变更:请求体为标准 GraphQL mutation 文档,Schema 覆盖各域 REST 的等价创建、更新与删除操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | string | 是 | — | GraphQL 变更文档字符串(如 mutation CreateSupportTeam(...) { ... })。 |
variables | body | object | 否 | {} | 变更输入变量对象,与 mutation 文档中的 $varName 变量声明对应。 |
operationName | body | string | 否 | null | 多操作文档中指定要执行的 mutation 名称。 |
输出:返回 200 OK + 标准 GraphQL 响应对象(含 data 与可选的 errors 数组)。
调用示例(创建智能客服值班团队并返回元数据):
curl -X POST "https://appbuild-sit.oceanbase.com/v1/graphql/mutation" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"operationName": "CreateOnCallTeam",
"query": "mutation CreateOnCallTeam($teamId: String!, $name: String!, $roles: [String!]) { teamsCreate(teamId: $teamId, name: $name, roles: $roles) { _id _createdAt _updatedAt name total } }",
"variables": {
"teamId": "team_oncall_2026",
"name": "企业智能客服 7x24 值班组",
"roles": ["owner", "dispatcher", "specialist"]
}
}'响应示例(200 OK):
{
"data": {
"teamsCreate": {
"_id": "team_oncall_2026",
"_createdAt": "2026-10-22T09:12:30.000+00:00",
"_updatedAt": "2026-10-22T09:12:30.000+00:00",
"name": "企业智能客服 7x24 值班组",
"total": 0
}
}
}部分失败/业务错误响应示例(200 OK 携带 errors[]):
{
"errors": [
{
"message": "Team with the requested ID already exists.",
"locations": [
{
"line": 1,
"column": 78
}
],
"path": [
"teamsCreate"
]
}
],
"data": {
"teamsCreate": null
}
}错误与边界
GraphQL 接口存在两层错误处理机制:传输/网关层错误(返回非 2xx HTTP 状态码)与 GraphQL 执行层错误(返回 200 OK 并在 errors[] 中列出):
| 层级 | HTTP 状态码 | 错误类型 (type) 或表现 | 触发原因 | 排障与重试建议 |
|---|---|---|---|---|
| 网关认证层 | 401 Unauthorized | general_access_forbidden | X-Appwrite-Project 或 X-Appwrite-Key 缺失、不匹配 | 核对项目 ID(如 enterprise-ai-hub-210)与 API Key 是否属于同一环境 |
| 网关权限层 | 401 Unauthorized | general_unauthorized_scope | API Key 未勾选 graphql 基础 scope | 在控制台「项目设置 -> API Keys」中为该 Key 勾选 graphql 及对应业务域 scope |
| 网关限流层 | 429 Too Many Requests | general_rate_limit_exceeded | 超过每分钟 60 次 GraphQL 调用配额 | 读取 Retry-After 响应头执行指数退避,或将多次零散查询合并为单次多字段 GraphQL 查询 |
| 查询复杂度边界 | 200 OK (errors[]) | Max query depth exceeded | 查询嵌套深度超过平台上限(默认 10 层) | 拆分深层嵌套选择集,剔除不必要的循环关联引用 |
| 业务 Resolver 层 | 200 OK (errors[]) | errors[0].message + path | 下游资源不存在(404)、唯一键冲突(409)或缺少子域 scope | 业务代码不能仅判断 response.status === 200,必须检查 body.errors 是否为空数组或未定义 |
与 Server SDK 的对应
各语言 Server SDK 均提供 Graphql 服务类,封装了上述两个 HTTP 端点的调用:
Server SDK service.method | Node.js / Python / Java / Go 方法名 | HTTP 方法与路径 | 说明 |
|---|---|---|---|
Graphql.query | graphql.query({ query }) | POST /v1/graphql | 传入包含 query、variables、operationName 的 Map/Object 执行查询 |
Graphql.mutation | graphql.mutation({ query }) | POST /v1/graphql/mutation | 传入包含 query、variables、operationName 的 Map/Object 执行变更 |