查询频道状态
三种服务端读取操作分别用于列出占用中的频道、查看单个频道,以及列出 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,
},
});import os
from bird import Bird
client = Bird(
api_key=os.environ["BIRD_API_KEY"],
realtime_key=os.environ["BIRD_REALTIME_KEY"],
realtime_secret=os.environ["BIRD_REALTIME_SECRET"],
)client, err := bird.NewClient(
option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
option.WithRealtimeCredentials(os.Getenv("BIRD_REALTIME_KEY"), os.Getenv("BIRD_REALTIME_SECRET")),
)
if err != nil {
log.Fatal(err)
}use MessageBird\Bird;
use MessageBird\RealtimeOptions;
$bird = new Bird(
getenv('BIRD_API_KEY') ?: '',
realtime: new RealtimeOptions(
key: getenv('BIRD_REALTIME_KEY') ?: '',
secret: getenv('BIRD_REALTIME_SECRET') ?: '',
),
);哪些频道处于占用状态
const { data } = await bird.realtime.channels.list(appId, { prefix: "presence-" });
for (const channel of data) {
console.log(channel.name);
}channels = client.realtime.channels.list(app_id, prefix="presence-")
for channel in channels.data:
print(channel.name)channels, err := client.Realtime.Channels.List(context.Background(), appID, bird.RealtimeChannelListParams{
Prefix: "presence-",
})
if err != nil {
log.Fatal(err)
}
for _, ch := range channels.Data {
fmt.Println(ch.Name)
}$channels = $bird->realtime->channels->list($appId, ['prefix' => 'presence-']);
foreach ($channels->getData() ?? [] as $channel) {
echo $channel->getName(), "\n";
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels?prefix=presence-" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"只要至少有一个连接订阅了某个频道,该频道就会出现在列表中。频道不需要单独创建或注册,因此空频道不会出现。使用 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 workchannel = client.realtime.channels.get(app_id, "presence-lobby", include=["member_count"])
if not channel.occupied:
return # nobody is listening; skip the workchannel, err := client.Realtime.Channels.Get(context.Background(), appID, "presence-lobby", bird.RealtimeChannelGetParams{
Include: []bird.RealtimeChannelInclude{bird.RealtimeIncludeMemberCount},
})
if err != nil {
log.Fatal(err)
}
if !channel.Occupied {
return // nobody is listening; skip the work
}$channel = $bird->realtime->channels->get($appId, 'presence-lobby', ['include' => ['member_count']]);
if (!$channel->getOccupied()) {
return; // nobody is listening; skip the work
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels/presence-lobby?include=member_count" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"计数,通过 include
include 可重复使用,且只接受两个值:
- member_count 是不同成员的数量,仅适用于 presence 频道。
- connection_count 是订阅该频道的连接数,需要应用启用连接计数设置。
任何其他值会返回 400 Bad Request。API 在以下情况也会返回 400 Bad Request:在非 presence 频道上请求 member_count、列表请求没有 presence 前缀,或连接计数被禁用时请求 connection_count。
请求属性会额外计入一条消息的用量。当 occupied 已经能回答你的问题时,省略属性即可。
谁在线
const { members } = await bird.realtime.channels.members(appId, "presence-lobby");
for (const member of members) {
console.log(member.member_id);
}presence = client.realtime.channels.members(app_id, "presence-lobby")
for member in presence.members:
print(member.member_id)members, err := client.Realtime.Channels.Members(context.Background(), appID, "presence-lobby")
if err != nil {
log.Fatal(err)
}
for _, m := range members.Members {
fmt.Println(m.MemberId)
}$presence = $bird->realtime->channels->members($appId, 'presence-lobby');
foreach ($presence->getMembers() ?? [] as $member) {
echo $member->getMemberId(), "\n";
}curl "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/channels/presence-lobby/members" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
-H "X-Realtime-Secret: $BIRD_REALTIME_SECRET"响应仅包含成员 ID。member_info 会推送给已订阅的客户端,无法通过此 REST 操作获取。将这些 ID 与你自己的记录关联,即可渲染名称或头像。参见列出频道成员。
发布时读取状态
发布时,使用 include 可在发布时返回每个目标频道的相同计数。参见发布时读取频道状态。
时间点行为
每次响应都是一个时间点快照,可能立即过时。适合用于一次性决策,而非通过轮询获取持续状态。
如需持续状态,请将端点订阅到 Realtime webhook 组。realtime.channel_existence 报告频道的占用和腾空事件,realtime.presence 报告成员变更,realtime.connection_count 报告连接数变更。使用频道状态读取来初始化或校正你存储的视图。
后续步骤
- 发布事件涵盖发布、批量发送以及 include 快捷方式。
- Presence 频道解释成员、连接以及 member_info。
- Realtime 概览解释应用、密钥以及用量的查看位置。
相关资源
继续查阅此主题的文档、指南和示例。资源为英文。