实时订阅
这是什么 / 何时用
Realtime 通过 WebSocket 把项目内的数据变更推送到浏览器:订阅某一行、某张表全部行、文件变化或账号事件,收到事件后即时刷新 UI(如看板、协作列表、上传进度)。客户端 SDK 建立 WebSocket 连接并按通道(channel)分发事件;服务端/Console 场景由 Console SDK 的 realtime 包装提供。
前置
- 客户端 SDK(client-sdk/web.md):浏览器场景使用用户 Session;只能收到当前身份按行级/表级权限可见的事件。
- 已初始化的
Client(setEndpoint+setProject);WebSocket 端点默认由 endpoint 推导,特殊网络可用setEndpointRealtime()覆盖。 - 订阅 TablesDB 行通道要求对应表/行对当前用户可读(行级/表级权限模型见 permissions 文档)。
使用骨架
- 从 SDK 导入
Realtime与Channel,构造通道: - 行:
Channel.tablesdb('DATABASE_ID').table('TABLE_ID').row('ROW_ID');省略行 ID(.row())即订阅该表全部行。 - 文件:
Channel.files()(全部文件变化)。 - 账号:
Channel.account()(当前账号相关事件)。
- 行:
- 订阅:
await realtime.subscribe(channelOrChannels, callback)——入参可以是单个通道或通道数组(一次订阅多通道);返回订阅对象。 - 在回调里按
event.type/event.data处理create/update/delete等事件负载。 - 结束单个订阅用
await sub.unsubscribe()(保留连接给其他订阅);完全关闭连接用Realtime.disconnect()。 - 动态调整:订阅对象提供
update({ channels, queries }),可在不重建 WebSocket 的情况下替换通道与过滤条件。 - Console SDK 场景(管理面板):
realtime.forProject(region, channels, callback)或realtime.forConsole(region, channels, callback),返回取消函数。
关键参数与返回
subscribe(channels, callback):channels为通道对象/字符串或其数组;通道对象可.toString()后作为字符串使用。- 订阅对象:
unsubscribe()(仅移除本订阅)、update(changes)(服务端原地更新通道/查询)、close()(unsubscribe+ 最后一个订阅时自动断连的兼容别名)。 - 回调事件:
RealtimeResponseEvent,含事件类型与数据负载;连接级控制(createSocket/closeSocket/disconnect)由 SDK 内部管理。 - 行订阅支持查询过滤:构造订阅时传入
queries(Query 字符串数组),仅接收匹配条件的行事件。
错误与边界
- 客户端行级权限边界:无权读取的行不会推送事件;
Role.label()/Role.guests()一类权限串不能用于客户端的行权限声明(会 401),需要在表/行权限里正确配置后由服务端过滤。 - 断线由 SDK 自动重连;重连后订阅通过服务端会话恢复,但业务侧不应假设"必达"——关键状态仍以 API 查询为准。
close()是兼容别名:优先用unsubscribe()做单订阅拆卸、disconnect()做整体关闭,避免语义混淆。- 服务端 Node SDK 没有 Realtime 服务:实时推送是客户端(浏览器)与 Console 面板能力。
SDK 类别差异
- 客户端 SDK(client-sdk/web.md):
Realtime+Channel全量能力(行/文件/账号、多通道、查询过滤、presence 更新)。 - Console SDK(console-sdk/nodejs.md):
realtime.forProject()/realtime.forConsole()包装,用于管理面板实时刷新。 - Server SDK(server-sdk/nodejs.md):无 Realtime 服务;服务端感知变更用 Webhooks(misc/webhooks.md)。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
订阅通道与事件处理
从 Channel 构造通道——行通道 .row('<rowId>') 为单行、省略行 ID 即订阅该表全部行,另有文件 Channel.files() 与账号 Channel.account();subscribe 接受单个通道或通道数组,回调里按 event.type / event.data 处理 create / update / delete 等负载。(仅 Web 客户端面:Server SDK 无 Realtime 服务、REST 无实时端点,均无页签。)
- Web(用户 Session)
import { Realtime, Channel } from 'agentbase-web-sdk'; // 前提:用户已登录,client 已初始化
const realtime = new Realtime(client);
const sub = await realtime.subscribe(
[
Channel.tablesdb('app-db').table('tasks').row(), // 全部行;.row('<rowId>') 为单行
Channel.files(), // 文件变化
Channel.account() // 当前账号事件
],
(event) => {
console.log(event.type, event.data); // create / update / delete 等负载
}
);查询过滤
行通道支持 queries 过滤(Query 字符串数组),仅接收匹配条件的行事件;过滤条件用订阅对象的 update 原地设置,无需重连。(仅 Web 客户端面。)
- Web(用户 Session)
import { Query } from 'agentbase-web-sdk';
await sub.update({
queries: [Query.equal('status', 'open')] // 仅推送 status=open 的行事件
});拆卸与关闭
单订阅用 unsubscribe() 拆卸(连接保留给其他订阅);完全关闭用 Realtime.disconnect()。close() 是兼容别名:等价 unsubscribe,且在最后一个订阅拆卸时自动断连。(仅 Web 客户端面。)
- Web(用户 Session)
await sub.unsubscribe(); // 拆卸单个订阅(保留连接给其他订阅)
Realtime.disconnect(); // 关闭整个连接
// sub.close() 为兼容别名:unsubscribe + 最后一个订阅时自动断连动态调整
update({ channels, queries }) 在不重建 WebSocket 的情况下替换通道与过滤条件(服务端原地更新)。(仅 Web 客户端面。)
- Web(用户 Session)
await sub.update({
channels: [Channel.tablesdb('app-db').table('tasks').row()], // 换通道(如改为全表行)
queries: [Query.equal('status', 'done')] // 同时换过滤
});示例指引
- JavaScript(浏览器订阅行/文件/账号通道):examples/javascript.md
事实源
skills/ob-agentbase/references/client-sdks/web.md(实时订阅节)skills/ob-agentbase/references/team-kanban-demo.md(全表行订阅实证)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/client-web/src/services/realtime.ts、channel.ts;packages/sdks/console-web/src/sdk.ts)