Consultando o estado de canais
Três leituras do lado do servidor listam canais ocupados, inspecionam um canal e listam os membros de um canal de presença. Autentique cada solicitação com a sua chave Bird API e a key e secret do app Realtime.
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') ?: '',
),
);Quais canais estão ocupados
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"Um canal aparece na lista enquanto pelo menos uma conexão estiver inscrita. Canais não são criados nem registrados separadamente, então canais vazios não aparecem. Use prefix para restringir o resultado a uma família como presence- ou orders-.
A resposta não é paginada e retorna todos os canais ocupados em um snapshot ao vivo. Consulte Listar canais Realtime.
Inspecionar um canal
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"Um nome desconhecido ou não utilizado retorna 200 OK com occupied: false. Use esse resultado para evitar trabalho quando nenhuma conexão pode recebê-lo. Consulte Obter um canal Realtime.
Contagens, via include
include é repetível e aceita exatamente dois valores:
- member_count é o número de membros distintos e funciona apenas em canais de presença.
- connection_count é o número de conexões inscritas no canal e requer a configuração de contagem de conexões do app.
Qualquer outro valor retorna 400 Bad Request. API também retorna 400 Bad Request para member_count em um canal que não é de presença, uma solicitação de listagem sem prefixo de presença, ou connection_count quando a contagem de conexões está desativada.
Solicitar atributos conta como uma mensagem extra no consumo. Omita-os quando occupied responder à sua pergunta.
Um membro pode manter várias conexões. Uma sala com três pessoas, cada uma com duas abas abertas, reporta um member_count de 3 e um connection_count de 6. Canais de presença explica a distinção.
Quem está presente
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"A resposta contém apenas IDs de membros. member_info é entregue aos clientes inscritos e não está disponível por meio desta operação REST. Associe os IDs aos seus próprios registros para exibir nomes ou avatares. Consulte Listar membros do canal.
Lendo o estado enquanto você publica
Ao publicar, use include para retornar as mesmas contagens de cada canal de destino no momento da publicação. Consulte Lendo o estado do canal enquanto você publica.
Comportamento pontual
Cada resposta é um snapshot pontual e pode se tornar obsoleta imediatamente. Use-a para decisões pontuais em vez de polling para estado contínuo.
Para estado contínuo, inscreva um endpoint nos grupos de webhook do Realtime. realtime.channel_existence reporta canais ocupados e desocupados, realtime.presence reporta alterações de membros e realtime.connection_count reporta alterações na contagem de conexões. Use leituras de estado de canal para inicializar ou reconciliar a sua visão armazenada.
Próximos passos
- Publicando eventos aborda publicação, envio em lote e o atalho include.
- Canais de presença explica membros, conexões e member_info.
- Visão geral do Realtime explica apps, chaves e onde o consumo aparece.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Explore a funcionalidadeRealtimeSiga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first realtime event
Experimente na prática e obtenha um resumo de implementação