Sign inGet started

查询频道状态

三种服务端读取操作分别用于列出占用中的频道、查看单个频道,以及列出 presence 频道的成员。每个请求需使用你的 Bird API 密钥以及 Realtime 应用的 key 和 secret 进行身份验证。
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
  },
});

哪些频道处于占用状态

const { data } = await bird.realtime.channels.list(appId, { prefix: "presence-" });

for (const channel of data) {
  console.log(channel.name);
}
只要至少有一个连接订阅了某个频道,该频道就会出现在列表中。频道不需要单独创建或注册,因此空频道不会出现。使用 prefix 将结果限制到某一类频道,例如 presence-orders-
响应不分页,会在一次实时快照中返回所有占用中的频道。参见列出 Realtime 频道

查看单个频道

const channel = await bird.realtime.channels.get(appId, "presence-lobby", {
  include: ["member_count"],
});

if (!channel.occupied) return; // nobody is listening; skip the work
未知或未使用的名称会返回 200 OKoccupied: false。利用此结果可以在没有连接能接收时跳过处理。参见获取 Realtime 频道

计数,通过 include

include 可重复使用,且只接受两个值:
  • member_count 是不同成员的数量,仅适用于 presence 频道。
  • connection_count 是订阅该频道的连接数,需要应用启用连接计数设置。
任何其他值会返回 400 Bad Request。API 在以下情况也会返回 400 Bad Request:在非 presence 频道上请求 member_count、列表请求没有 presence 前缀,或连接计数被禁用时请求 connection_count
请求属性会额外计入一条消息的用量。当 occupied 已经能回答你的问题时,省略属性即可。
一个成员可以拥有多个连接。一个房间里有三个人,每人打开了两个标签页,member_count 报告为 3,connection_count 报告为 6。Presence 频道解释了两者的区别。

谁在线

const { members } = await bird.realtime.channels.members(appId, "presence-lobby");

for (const member of members) {
  console.log(member.member_id);
}
响应仅包含成员 ID。member_info 会推送给已订阅的客户端,无法通过此 REST 操作获取。将这些 ID 与你自己的记录关联,即可渲染名称或头像。参见列出频道成员

发布时读取状态

发布时,使用 include 可在发布时返回每个目标频道的相同计数。参见发布时读取频道状态

时间点行为

每次响应都是一个时间点快照,可能立即过时。适合用于一次性决策,而非通过轮询获取持续状态。
如需持续状态,请将端点订阅到 Realtime webhook 组。realtime.channel_existence 报告频道的占用和腾空事件,realtime.presence 报告成员变更,realtime.connection_count 报告连接数变更。使用频道状态读取来初始化或校正你存储的视图。

后续步骤