Docs
文档目录

实时订阅

这是什么 / 何时用

Realtime 通过 WebSocket 把项目内的数据变更推送到浏览器:订阅某一行、某张表全部行、文件变化或账号事件,收到事件后即时刷新 UI(如看板、协作列表、上传进度)。客户端 SDK 建立 WebSocket 连接并按通道(channel)分发事件;服务端/Console 场景由 Console SDK 的 realtime 包装提供。

前置

使用骨架

  1. 从 SDK 导入 Realtime 与 Channel,构造通道:

    • 行:Channel.tablesdb('DATABASE_ID').table('TABLE_ID').row('ROW_ID');省略行 ID(.row())即订阅该表全部行。

    • 文件:Channel.files()(全部文件变化)。

    • 账号:Channel.account()(当前账号相关事件)。

  2. 订阅:await realtime.subscribe(channelOrChannels, callback)——入参可以是单个通道或通道数组(一次订阅多通道);返回订阅对象。

  3. 在回调里按 event.type / event.data 处理 create / update / delete 等事件负载。

  4. 结束单个订阅用 await sub.unsubscribe()(保留连接给其他订阅);完全关闭连接用 Realtime.disconnect()。

  5. 动态调整:订阅对象提供 update({ channels, queries }),可在不重建 WebSocket 的情况下替换通道与过滤条件。

  6. Console SDK 场景(管理面板):realtime.forProject(region, channels, callback) 或 realtime.forConsole(region, channels, callback),返回取消函数。

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

订阅通道与事件处理

从 Channel 构造通道——行通道 .row('<rowId>') 为单行、省略行 ID 即订阅该表全部行,另有文件 Channel.files() 与账号 Channel.account();subscribe 接受单个通道或通道数组,回调里按 event.type / event.data 处理 create / update / delete 等负载。(仅 Web 客户端面:Server SDK 无 Realtime 服务、REST 无实时端点,均无页签。)

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 客户端面。)

import { Query } from 'agentbase-web-sdk';

await sub.update({
    queries: [Query.equal('status', 'open')]   // 仅推送 status=open 的行事件
});

拆卸与关闭

单订阅用 unsubscribe() 拆卸(连接保留给其他订阅);完全关闭用 Realtime.disconnect()。close() 是兼容别名:等价 unsubscribe,且在最后一个订阅拆卸时自动断连。(仅 Web 客户端面。)

await sub.unsubscribe();   // 拆卸单个订阅(保留连接给其他订阅)
Realtime.disconnect();     // 关闭整个连接
// sub.close() 为兼容别名:unsubscribe + 最后一个订阅时自动断连

动态调整

update({ channels, queries }) 在不重建 WebSocket 的情况下替换通道与过滤条件(服务端原地更新)。(仅 Web 客户端面。)

await sub.update({
    channels: [Channel.tablesdb('app-db').table('tasks').row()],   // 换通道(如改为全表行)
    queries: [Query.equal('status', 'done')]                       // 同时换过滤
});

示例指引