GraphQL
这是什么 / 何时用
以 GraphQL 查询/变更访问平台数据面,查询语法与 REST 数据模型一致。客户端与服务端都可用(客户端受用户 Session 与数据面权限约束)。
使用骨架
graphql.query({ query })执行只读查询;graphql.mutation({ query })执行变更。
错误与边界
- GraphQL 与 REST 计入同一项目限流体系(限流 60 次/分钟)。
- GraphQL
errors不产生 HTTP 错误码:调用方必须检查响应体的errors字段,不要只看 HTTP 状态。
各语言调用示例
客户端与服务端均可用;Web 页签走用户 Session,受数据面权限约束。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Graphql } from 'agentbase-node-sdk';
const graphql = new Graphql(client);
const result = await graphql.query({ query: 'query { account { name email } }' });
await graphql.mutation({ query: 'mutation { /* 变更语句同 REST 数据模型 */ }' });import { Graphql } from 'agentbase-web-sdk'; // 前提:用户已登录
const graphql = new Graphql(client);
const result = await graphql.query({ query: 'query { account { name email } }' });Object result = graphql.query(Map.of("query", "query { account { name email } }"));
graphql.mutation(Map.of("query", "mutation { /* 变更语句同 REST 数据模型 */ }"));from agentbase.services.graphql import Graphql
graphql = Graphql(client)
result = graphql.query(query='query { account { name email } }')
graphql.mutation(query='mutation { /* 变更语句同 REST 数据模型 */ }')graphql := agentbase.NewGraphql(cl) // facade 构造器;cl 为已装载 API Key 的 Client
result, _ := graphql.Query(map[string]interface{}{"query": "query { account { name email } }"})
_ = result
graphql.Mutation(map[string]interface{}{"query": "mutation { /* 变更语句同 REST 数据模型 */ }"})curl -sS -X POST "$APPBASE_ENDPOINT/v1/graphql" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"query":"query { account { name email } }","variables":{}}'
# 变更:POST /v1/graphql/mutation(body 同为 query / variables)SDK 类别差异
- Server SDK / Console SDK:全量。
- 客户端 SDK(client-sdk/web.md):可用,受用户 Session 与行级权限约束。
事实源
skills/ob-agentbase/references/server-sdks/nodejs.md(模块表)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/graphql.ts方法面)