Docs
文档目录

GraphQL API

运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。

以 GraphQL 查询(Query)与变更(Mutation)协议访问 Agentbase 平台数据面:查询语法、权限判定、限流配额与 REST 数据模型保持严格一致,支持单次请求聚合多域资源读取与字段级投影裁剪。

服务与资源边界

GraphQL API 为项目内各核心业务域(账户与用户、团队、TablesDB / DocumentsDB 数据库、Storage 存储桶与文件、Functions 函数执行等)提供统一的图查询与变更入口。其核心边界如下:

资源与基础路径

模型名称方向核心字段说明
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/graphqlJSON 载荷模式或纯 GraphQL 查询文本模式

Scope 与资源级权限判定

端点总览

GraphQL 模块提供两个核心 HTTP POST 端点,分别服务于只读查询与状态变更(底层的执行管线共享同一 Schema 解析器,拆分为两个路径便于网关层按路径配置读写分离限流与审计策略):

能力分类端点路径幂等性速率限制典型应用场景
数据查询(Query)POST /v1/graphql是(仅执行 query 操作时)60 次/分钟聚合查询团队、用户、业务表记录(如客服工单 customer_tickets)及存储桶文件列表
状态变更(Mutation)POST /v1/graphql/mutation否(取决于具体变更操作)60 次/分钟创建团队、写入/更新业务表行记录、创建函数执行或更新用户偏好配置

端点清单

方法 + 路径Scope幂等性用途
POST /graphqlgraphql + 目标域读取 scope是执行 GraphQL 查询(Query)操作
POST /graphql/mutationgraphql + 目标域写入 scope否执行 GraphQL 变更(Mutation)操作

端点详解

查询与变更执行机制

  1. 解析与语法树校验(Parse & Validate):服务端接收 query 字符串后解析为 AST,校验字段名称、参数类型及嵌套深度。默认最大查询嵌套深度(Max Query Depth)为 10 层,单次批量操作上限受项目配额约束,防止恶意循环嵌套查询耗尽 CPU。

  2. 变量绑定(Variables Substitution):推荐将动态过滤条件(如项目内工单 ID TK-20261022-001、分页 queries 数组)提取至 variables JSON 对象中传入,以便服务端复用已编译的查询计划并彻底避免字符串拼接注入风险。

  3. 字段命名映射规则:

    • 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 的等价读取操作。

输入:

参数位置类型必填默认/枚举说明
querybodystring是—GraphQL 查询文档字符串(如 query ListSupportTeams(...) { ... })。
variablesbodyobject否{}查询变量键值对对象,与 query 文档中的 $varName 变量声明严格对应。
operationNamebodystring否null当 query 文档包含多个具名操作时,显式指定本次要执行的操作名称。

输出:返回 200 OK + 标准 GraphQL 响应对象:

字段类型说明
dataobject | null按查询选择集(Selection Set)裁剪后的结构化结果对象;顶层执行完全失败时为 null
errorsarray可选错误列表;完全成功时省略该字段。每个元素包含 message、locations(line/column)与 path

调用示例(聚合查询项目内团队列表与客服业务库信息):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/graphql" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @- \
  -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 的等价创建、更新与删除操作。

输入:

参数位置类型必填默认/枚举说明
querybodystring是—GraphQL 变更文档字符串(如 mutation CreateSupportTeam(...) { ... })。
variablesbodyobject否{}变更输入变量对象,与 mutation 文档中的 $varName 变量声明对应。
operationNamebodystring否null多操作文档中指定要执行的 mutation 名称。

输出:返回 200 OK + 标准 GraphQL 响应对象(含 data 与可选的 errors 数组)。

调用示例(创建智能客服值班团队并返回元数据):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/graphql/mutation" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @- \
  -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 Unauthorizedgeneral_access_forbiddenX-Appwrite-Project 或 X-Appwrite-Key 缺失、不匹配核对项目 ID(如 enterprise-ai-hub-210)与 API Key 是否属于同一环境
网关权限层401 Unauthorizedgeneral_unauthorized_scopeAPI Key 未勾选 graphql 基础 scope在控制台「项目设置 -> API Keys」中为该 Key 勾选 graphql 及对应业务域 scope
网关限流层429 Too Many Requestsgeneral_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.methodNode.js / Python / Java / Go 方法名HTTP 方法与路径说明
Graphql.querygraphql.query({ query })POST /v1/graphql传入包含 query、variables、operationName 的 Map/Object 执行查询
Graphql.mutationgraphql.mutation({ query })POST /v1/graphql/mutation传入包含 query、variables、operationName 的 Map/Object 执行变更