实时数据库(WebSocket)

该功能可实现订阅数据表的数据增删改变化,当表数据改变时,客户端可以实时接收到数据的变化。

danger 该操作适用于 SDK version >= 1.0.0-alpha-3

操作步骤

info 使用实时数据库功能前需要先进行登录操作

1.通过 tableName 实例化一个 TableObject 对象,操作该对象即相当于操作对应的数据表,这里推荐用 tableName

  1. TableObject tableObject = new TableObject(tableName);

参数说明

名称 类型 必填 说明
tableName String 数据表名

info 实时数据库功能无法订阅内置数据表,如 _userprofile 表、_richtextcontent 表等

2.发起数据表订阅操作

var myEvent = tableObject.subscribe(event, where, onInit, onEvent, onError);

参数说明

名称 类型 必填 说明
event String 表数据变化的类型,有三种:create、update 和 delete
where Where 查询条件
onInit Function 订阅成功回调
onEvent Function 订阅数据变化回调
onError Function 订阅动作出错回调

info

  • createupdatedelete 三种数据变化类型需要分别订阅
  • onInit 回调函数将在订阅动作初始化成功时调用,一次 subscribe 订阅动作会触发一次
  • onEvent 回调函数将在数据表每次有相应动作变化时调用,参数是数据表变化了的数据项,三种事件类型对应得到的回调参数对象结构见下表
  • onError 回调函数将在订阅动作出错是调用,参数是错误信息

onevent 回调函数参数说明

create 事件得到的 WampCallback 类型:

名称 类型 说明
event String 事件类型,返回 “on_create”
schema_id int 订阅的数据表的 ID
schema_name String 订阅的数据表的表名
id String 新增的数据行的 ID
after Map 新增的数据行对象
before Map 空对象

update 事件得到的 WampCallback 类型:

名称 类型 说明
event String 事件类型,返回 “on_update”
schema_id int 订阅的数据表的 ID
schema_name String 订阅的数据表的表名
id String 更新的数据行的 ID
after Map 更新后的数据行对象
before Map 更新前的数据行对象

delete 事件得到的 WampCallback 类型:

名称 类型 说明
event String 事件类型,返回 “on_delete”
schema_id int 订阅的数据表的 ID
schema_name String 订阅的数据表的表名
id String 删除的数据行的 ID
after Map 空对象
before Map 删除前的数据行对象

通过上面的步骤,即可订阅某个数据表的其中一个数据变化动作(新增、更新或删除)的变化,具体操作阅读以下内容。

订阅数据表

请求示例

  1. // 订阅 tableName 为 'product' 的数据表的新增数据动作
  2. Future subscribeEvent(eventType) async {
  3. String tableName = 'product';
  4. TableObject tableObject = new TableObject(tableName);
  5. try {
  6. WampSubscriber createEvent = await tableObject.subscribe(
  7. eventType,
  8. onInit: () {
  9. print('订阅成功==>');
  10. },
  11. onEvent: (result) {
  12. print('订阅推送==> $eventType');
  13. print(result.event);
  14. },
  15. onError: (error) {
  16. print('订阅断开==>');
  17. print(error.message);
  18. print(error.details);
  19. },
  20. );
  21. } catch (e) {
  22. print(e.toString());
  23. }
  24. }

返回示例

onevent 回调函数中的 res 对象结构如下:

数据表新增数据(create)返回的对象结构:

  1. {
  2. "after": {
  3. "text": "123",
  4. "_read_perm": ["user:anonymous"],
  5. "_write_perm": ["user:anonymous"],
  6. "created_at": 1594265027,
  7. "updated_at": 1594265027,
  8. "created_by": 195448780235670,
  9. "id": "5f068dc32dc610747781efcc"
  10. },
  11. "before": {},
  12. "event": "on_create",
  13. "schema_id": 968,
  14. "schema_name": "product",
  15. "id": "5f068dc32dc610747781efcc"
  16. }

数据表更新数据(update)返回的对象结构:

  1. {
  2. "after": {
  3. "text": "123123",
  4. "_read_perm": ["user:anonymous"],
  5. "_write_perm": ["user:anonymous"],
  6. "created_at": 1594265027,
  7. "updated_at": 1594265113,
  8. "created_by": 195448780235670,
  9. "id": "5f068dc32dc610747781efcc"
  10. },
  11. "before": {
  12. "text": "123",
  13. "_read_perm": ["user:anonymous"],
  14. "_write_perm": ["user:anonymous"],
  15. "created_at": 1594265027,
  16. "updated_at": 1594265027,
  17. "created_by": 195448780235670,
  18. "id": "5f068dc32dc610747781efcc"
  19. },
  20. "event": "on_update",
  21. "schema_id": 968,
  22. "schema_name": "product",
  23. "id": "5f068dc32dc610747781efcc"
  24. }

数据表删除数据(delete)返回的对象结构:

  1. {
  2. "after": {},
  3. "before": {
  4. "text": "123123",
  5. "_read_perm": ["user:anonymous"],
  6. "_write_perm": ["user:anonymous"],
  7. "created_at": 1594265027,
  8. "updated_at": 1594265113,
  9. "created_by": 195448780235670,
  10. "id": "5f068dc32dc610747781efcc"
  11. },
  12. "event": "on_delete",
  13. "schema_id": 968,
  14. "schema_name": "product",
  15. "id": "5f068dc32dc610747781efcc"
  16. }

err 对象结构请参考错误码和 HError 对象

info 当 WebSocket 连接意外断开时,SDK 会采用指数退避算法的机制,自动尝试重连。

另外,在知晓云控制台中手动删除数据时,如需触发删除数据动作的订阅通知,需要勾上「删除动作触发触发器」设置,如下图

删除数据触发 WebSocket

按查询条件订阅

info 条件订阅使用方法与查询数据(Where)一致,可参考:查询数据。 Websocket 按条件订阅目前仅支持比较(compare)查询。

按条件订阅支持以下操作符:

数据类型 可使用的查询操作 说明
string =, != -
integer =, >, >=, <, <=, != -
number =, >, >=, <, <=, != -
boolean =, != -
date =, >, >=, <, <=, != -

请求示例

  1. // 订阅 tableName 为 'product' 的数据表的新增数据动作
  2. Future subscribeEvent(eventType) async {
  3. String tableName = 'product';
  4. TableObject tableObject = new TableObject(tableName);
  5. try {
  6. WampSubscriber createEvent = await tableObject.subscribe(
  7. eventType,
  8. onInit: () {
  9. print('订阅成功==>');
  10. },
  11. onEvent: (result) {
  12. print('订阅推送==> $eventType');
  13. print(result.event);
  14. },
  15. onError: (error) {
  16. print('订阅断开==>');
  17. print(error.message);
  18. print(error.details);
  19. },
  20. where: Where.compare('text', '=', 'hello'),
  21. );
  22. } catch (e) {
  23. print(e.toString());
  24. }
  25. }

取消订阅

当实时数据库功能连接成功后,会一直保持订阅状态。如需断开连接,比如退出发起订阅的页面时,可根据需要主动发起取消订阅。

请求示例

  1. createEvent.unsubscribe(); // 取消订阅上述示例中数据表的新增数据动作