Interroger l'état des canaux
Trois lectures côté serveur listent les canaux occupés, inspectent un canal et listent les membres d'un canal de présence. Authentifiez chaque requête avec votre clé Bird API ainsi que la clé et le secret de l'application 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') ?: '',
),
);Quels canaux sont occupés
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"Un canal apparaît dans la liste tant qu'au moins une connexion y est abonnée. Les canaux ne sont ni créés ni enregistrés séparément : les canaux vides n'apparaissent donc pas. Utilisez prefix pour restreindre le résultat à une famille telle que presence- ou orders-.
La réponse n'est pas paginée et renvoie tous les canaux occupés en un seul instantané en temps réel. Voir Lister les canaux Realtime.
Inspecter un 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"Un nom inconnu ou inutilisé renvoie 200 OK avec occupied: false. Utilisez ce résultat pour éviter un traitement quand aucune connexion ne peut le recevoir. Voir Obtenir un canal Realtime.
Compteurs, via include
include est répétable et accepte exactement deux valeurs :
- member_count est le nombre de membres distincts et ne fonctionne que sur les canaux de présence.
- connection_count est le nombre de connexions abonnées au canal et nécessite que le paramètre de comptage des connexions de l'application soit activé.
Toute autre valeur renvoie 400 Bad Request. API renvoie aussi 400 Bad Request pour member_count sur un canal sans présence, pour une requête de liste sans préfixe de présence, ou connection_count lorsque le comptage des connexions est désactivé.
Demander des attributs compte comme un message supplémentaire dans votre consommation. Omettez-les quand occupied suffit à répondre à votre question.
Un même membre peut détenir plusieurs connexions. Une salle avec trois personnes ayant chacune deux onglets ouverts affiche un member_count de 3 et un connection_count de 6. Canaux de présence explique la distinction.
Qui est présent
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"La réponse ne contient que les identifiants des membres. member_info est transmis aux clients abonnés et n'est pas disponible via cette opération REST. Associez les identifiants à vos propres enregistrements pour afficher des noms ou des avatars. Voir Lister les membres d'un canal.
Lire l'état pendant la publication
Lors de la publication, utilisez include pour obtenir les mêmes compteurs pour chaque canal cible au moment de la publication. Voir Lire l'état des canaux pendant la publication.
Comportement à un instant donné
Chaque réponse est un instantané à un instant donné et peut devenir obsolète immédiatement. Utilisez-le pour des décisions ponctuelles plutôt que pour interroger l'état en continu.
Pour un état continu, abonnez un endpoint aux groupes de webhooks Realtime. realtime.channel_existence signale les canaux occupés et libérés, realtime.presence signale les changements de membres et realtime.connection_count signale les changements de compteur de connexions. Utilisez les lectures d'état des canaux pour initialiser ou réconcilier votre vue stockée.
Étapes suivantes
- Publier des événements couvre la publication, le regroupement par lots et le raccourci include.
- Canaux de présence explique les membres, les connexions et member_info.
- Vue d'ensemble Realtime explique les applications, les clés et où la consommation apparaît.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Explorer la fonctionnalitéRealtimeSuivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first realtime event
Essayez la pratique et obtenez un guide d'implémentation