Agentbase 云控制台
浏览全部文档 · 5/37
已支持已发布

快速开始：Auth、Row 与 Realtime

快速开始

完成目标

用应用终端用户的 Session 写入一条 Row，并只接收该用户有权读取的 Realtime 事件。这条路径同时验证 Platform、Auth、TablesDB Permission 与 WebSocket。

1 个有效 Session代表应用终端用户，不是 Console 账号
1 条可读取 Row符合 Table Column 与 Permission
1 次 Realtime 事件经过相同的 Project 与读取权限过滤

开始前准备

  • 在 Project 概览登记当前 Web Origin，并启用需要的客户端服务。
  • 创建 Database、Table 和一个可写的 title Column。
  • 为测试用户准备登录方式；Table 与 Row Permission 必须允许该用户创建和读取。

按步骤完成

  1. 登记 Web Platform

    在 Project 概览添加 Web Platform，Hostname 只填写当前应用域名，不包含路径。客户端请求必须使用相同 Project ID。

  2. 准备 Table 与 Permission

    创建 Database、Table 和 title Column。为登录用户或目标 Team 配置 create/read Permission；不要使用公开读写权限代替验收。

  3. 建立 Session 并订阅

    使用应用终端用户账号创建 Session，再订阅目标 Database、Table 的 Row Channel。先建立订阅，避免错过随后写入产生的事件。

  4. 写入 Row 并验收事件

    通过同一个客户端创建 Row，等待一次包含目标 Row ID 的事件，再主动关闭订阅。读取 Row 时应得到与写入一致的 title。

SDK 示例

SDK · TypeScript
import { Client } from 'agentbase-web-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>');
import { Account, TablesDB, Realtime, ID, Channel } from 'agentbase-web-sdk';

const account = new Account(client);
await account.createEmailPasswordSession({
  email: '<USER_EMAIL>',
  password: '<USER_PASSWORD>'
});

const tables = new TablesDB(client);
const realtime = new Realtime(client);
const subscription = await realtime.subscribe(
  Channel.tablesdb('<DATABASE_ID>').table('<TABLE_ID>').row(),
  event => console.log(event.events)
);

await tables.createRow({
  databaseId: '<DATABASE_ID>',
  tableId: '<TABLE_ID>',
  rowId: ID.unique(),
  data: { title: 'first row' }
});

await subscription.close();

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/tables/<TABLE_ID>/rows' \
  -X POST \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-JWT: <USER_JWT>' \
  -H 'Content-Type: application/json' \
  --data '{"rowId":"unique()","data":{"title":"first row"}}'

权限模型

Session/JWT 代表用户，写入先检查 Table create 权限，读取和 Realtime 投递再按 Table/Row read 权限过滤。服务端 API Key 可使用 rows.write/rows.read，但不应放进浏览器。

常见错误

现象处理建议
401 或 user_unauthorized确认请求使用了当前接口允许的 Session、JWT 或 API Key；不要把 Console Session 与 Project API Key 混用。
403 或 general_access_forbidden检查 API Key Scope、组织角色以及资源级 Permission；认证成功不等于拥有目标操作权限。
404核对资源 ID 与 Project；不可见资源可能与不存在资源使用相同响应，客户端不应据此探测资源。
429按响应的限流语义退避，避免并发重试放大请求。

当前限制

  • 客户端只能向已存在的 Table 写入符合 Column 定义的数据。
  • Realtime 是 WebSocket API；GraphQL Subscription 不受支持。
  • Channel 构造方法随 SDK 版本变化，安装时以目标包导出为准。

Appwrite 兼容说明

Auth、TablesDB 与 Realtime 保留常见 Appwrite 接入概念，但示例使用 Agentbase 包名与实际导出。

Agentbase 增强说明

Agentbase 可在相同 Project 边界继续组合 Aggregation、Schema Version、Memory 或 Moderation。

继续阅读