Salles pour petit groupe

Cet article décrit comment implémenter des salles pour petit groupe Microsoft Teams avec Azure Communication Services. Cette fonctionnalité permet aux utilisateurs d’Azure Communication Services dans des réunions Teams de participer à des salles pour petit groupe. Les administrateurs Teams contrôlent la disponibilité des salles pour petit groupe dans une réunion Teams avec une stratégie de réunion Teams. Vous trouverez des informations supplémentaires sur les salles pour petit groupe dans la documentation Teams.

Prérequis

• Compte Azure avec un abonnement actif. Voir Créer un compte gratuitement.
• Une ressource Communication Services déployée. Créez une ressource Communication Services.
• Un jeton d’accès utilisateur pour activer le client appelant. Pour plus d’informations, consultez Créer et gérer des jetons d’accès.
• L’organisateur de la réunion Teams doit affecter une stratégie de réunion Teams qui active les salles pour petit groupe. Consultez Stratégie de réunion Teams.
• Facultatif : suivez le guide de démarrage rapide permettant d’ajouter l’appel vocal à votre application.

Seuls les utilisateurs Microsoft 365 ayant le rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe peuvent gérer les salles pour petit groupe.

Support

Les tableaux suivants définissent la prise en charge des salles pour petit groupe dans Azure Communication Services.

Identités et types d’appels

Le tableau suivant indique la prise en charge des salles pour petit groupe pour un type d’appel et une identité spécifiques.

Opérations

Le tableau suivant indique la prise en charge des différentes API du Kit de développement logiciel (SDK) Appels liés à des types d’identités individuels.

[1] Seulement un utilisateur Microsoft 365 disposant du rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe.

[2] Les utilisateurs Microsoft 365 peuvent utiliser l’API Graph pour participer à une conversation de salle pour petit groupe. L’ID de thread de la conversation est fourni dans l’objet de salle pour petit groupe affectée.

SDK

Les tableaux suivants indiquent la prise en charge de la fonctionnalité de salle pour petit groupe dans les Kits de développement logiciel (SDK) individuels d’Azure Communication Services.

Installer le SDK

Utilisez la commande npm install pour installer le SDK Azure Communication Services Common et le SDK Azure Communication Services Calling pour JavaScript :

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

Initialiser les objets nécessaires

Une instance CallClient est requise pour la plupart des opérations d’appel. Lorsque vous créez une instance CallClient, vous pouvez la configurer avec des options personnalisées comme une instance Logger.

Avec l’instance CallClient, vous pouvez créer une instance CallAgent en appelant createCallAgent. Cette méthode renvoie un objet d’instance CallAgent de manière asynchrone.

La méthode createCallAgent utilise CommunicationTokenCredential comme argument. Elle accepte un jeton d’accès utilisateur.

Vous pouvez utiliser la méthode getDeviceManager sur l’instance CallClient pour accéder à deviceManager.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Comment gérer au mieux la connectivité du SDK à l’infrastructure Microsoft

L’instance Call Agent vous aide à gérer les appels (pour rejoindre ou démarrer des appels). Pour fonctionner, votre SDK d’appel doit se connecter à l’infrastructure Microsoft pour recevoir des notifications d’appels entrants et coordonner d’autres détails de l’appel. Votre Call Agent a deux états possibles :

Connecté : un Call Agent dont la valeur connectionStatue est égale à Connected signifie que le SDK client est connecté et capable de recevoir des notifications de l’infrastructure Microsoft.

Déconnecté : un Call Agent dont la valeur connectionStatue est égale à Disconnected indique qu’un problème empêche le SDK de se connecter correctement. Call Agent doit être recréé.

• invalidToken : si un jeton a expiré ou n’est pas valide, l’instance Call Agent se déconnecte avec cette erreur.
• connectionIssue : en cas de problème de connexion du client à l’infrastructure Microsoft, après plusieurs tentatives, Call Agent lève l’erreur connectionIssue.

Vous pouvez vérifier si votre Call Agent local est connecté à l’infrastructure Microsoft en inspectant la valeur actuelle de la propriété connectionState. Pendant un appel actif, vous pouvez écouter l’événement connectionStateChanged pour déterminer si Call Agent passe de l’état Connecté à l’état Déconnecté.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Implémenter des salles de petit groupe

BreakoutRooms est une feature de la classe Call. Vous devez d’abord importer les Features du package depuis le Kit de développement logiciel (SDK) Appelant :

import { Features} from "@azure/communication-calling";

Créer une fonctionnalité de salle pour petit groupe

Récupérez ensuite l’objet d’API de la fonctionnalité auprès de l’instance d’appel :

const breakoutRoomsFeature = mainMeetingCall.feature(Features.BreakoutRooms);

S’abonner aux événements de salle pour petit groupe

L’API BreakoutRooms vous permet de vous abonner aux événements BreakoutRooms. Un événement breakoutRoomsUpdated provient d’une instance de BreakoutRoomsCallFeature et contient des informations sur les salles pour petit groupe créées, mises à jour et affectées.

Pour recevoir les détails de la salle pour petit groupe, abonnez-vous à l’événement breakoutRoomsUpdated.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Gérer les événements de salle pour petit groupe

L’événement breakoutRoomsUpdated fournit une instance d’une des classes suivantes en tant que paramètre d’entrée. Vous pouvez utiliser la propriété type pour distinguer entre les types d’événements individuels.

• Classe BreakoutRoomsEvent : cet événement est déclenché quand un utilisateur disposant du rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe crée ou met à jour les salles pour petit groupe. Les utilisateurs Microsoft 365 disposant du rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe peuvent recevoir ce type d’événement. Les développeurs peuvent utiliser les salles pour petit groupe dans la propriété data pour afficher des détails sur toutes les salles pour petit groupe. Cette classe a une propriété type égale à "breakoutRooms".

    export interface BreakoutRoomsEvent {
      /**
       * Breakout room event type
      */
      type: "breakoutRooms",
      /**
       * list of Breakout rooms
      */
      data: BreakoutRoom[] | undefined;
    }
  

• Classe BreakoutRoomsSettingsEvent : quand un utilisateur disposant d’un rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe met à jour les paramètres d’une salle pour petit groupe, il déclenche cet événement. Les développeurs peuvent utiliser ces informations pour montrer le moment où la salle pour petit groupe se termine ou décider s’il faut afficher un bouton permettant de rejoindre la salle principale. Cette classe a une propriété type égale à "breakoutRoomSettings".

    export interface BreakoutRoomSettingsEvent {
      /**
      * Breakout room event type
      */
      type: "breakoutRoomSettings",
      /**
      * Breakout Room setting details
      */
      data: BreakoutRoomSettings | undefined;
    }
  

• Classe AssignedBreakoutRoomsEvent : cet événement est déclenché quand l’utilisateur est affecté à une salle pour petit groupe ou quand une salle pour petit groupe affectée est mise à jour. Les utilisateurs peuvent rejoindre la salle pour petit groupe quand la propriété state est définie sur open, quitter la salle pour petit groupe quand la propriété state est définie sur closed ou afficher les détails de la salle pour petit groupe. Cette classe a une propriété type égale à "assignedBreakoutRoom".

    export interface AssignedBreakoutRoomEvent {
      /**
       * Breakout room event type
       */
      type: "assignedBreakoutRoom";
      /**
       * Assigned breakout room details
       */
      data: BreakoutRoom | undefined;
    }
  

• Classe JoinBreakoutRoomsEvent : cet événement est déclenché quand le participant rejoint un appel d’une salle pour petit groupe. Cet événement peut se produire quand un utilisateur est déplacé automatiquement vers une salle pour petit groupe (autrement dit, si assignedBreakoutRoom a la propriété state définie sur open et que autoMoveParticipantToBreakoutRoom est défini sur true) ou quand un utilisateur rejoint explicitement une salle pour petit groupe (autrement dit, quand il appelle la méthode join sur l’instance assignedBreakoutRoom quand autoMoveParticipantToBreakoutRoom est défini sur false). La propriété data contient l’instance call de la salle pour petit groupe, que les développeurs peuvent utiliser pour contrôler l’appel de la salle pour petit groupe. Cette classe a une propriété type égale à "join".

    export interface JoinBreakoutRoomEvent {
      /**
       * Breakout room event type
       */
      type: "join";
      /**
       * Breakoutroom call object
       */
      data: Call | TeamsCall;
    }
  

Le code suivant vous montre des informations importantes reçues dans les événements de salle pour petit groupe :

    const breakoutRoomsUpdatedListener = (event) => {
    switch(event.type) {
        case "breakoutRooms":
          const breakoutRooms = event.data;
          console.log(`Breakout rooms are created or updated. There are ${breakoutRooms.length} breakout rooms in total.`);
          breakoutRooms.forEach((room)=>{
          console.log(`- ${room.displayName}`);
          });    
          break;
        case "assignedBreakoutRooms":
          const assignedRoom = event.data;
          console.log(`You are assigned to breakout room named: ${assignedRoom.displayName}`);      
          console.log(`Assigned breakout room thread Id: ${assignedRoom.threadId}`);
          console.log(`Automatically move participants to breakout room: ${assignedRoom.autoMoveParticipantToBreakoutRoom}`);
          console.log(`Assigned breakout room state : ${assignedRoom.state }`);      
          break;
        case "breakoutRoomsSettings":
          const breakoutRoomSettings = event.data;
          console.log(`Breakout room ends at: ${breakoutRoomSettings.roomEndTime}`);          
          console.log(`Disable the user to return to main meeting from breakout room call : ${breakoutRoomSettings.disableReturnToMainMeeting}`);         
          break;
        case "join":
          const breakoutRoomCall = event.data;
          console.log(`You have joined breakout room with call ID: ${breakoutRoomCall.id}`);      
          break;      
      }
    }
breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Lister les salles pour petit groupe disponibles

Les utilisateurs Microsoft 365 disposant du rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe peuvent accéder à toutes les salles pour petit groupe.

const breakoutRooms = breakoutRoomsFeature.breakoutRooms;
breakoutRooms.forEach((room)=>{
      console.log(`- ${room.displayName}`);
       }); 

Lister les invités

Un utilisateur Microsoft 365 disposant du rôle Organisateur, Co-organisateur ou Gestionnaire de salle pour petit groupe peut accéder aux participants affectés à des salles pour petit groupe individuelles.

breakoutRooms.forEach((room)=>{
      console.log(`${room.displayName}`);
      room.invitees.forEach((invitee) => {
          console.log(`- ${invitee.id}`);         
          })
      })

Se joindre à une salle pour petit groupe

Si la assignedBreakoutRoom a la propriété autoMoveParticipantToBreakoutRoom définie sur true, l’utilisateur est déplacé automatiquement vers la salle pour petit groupe quand la propriété state est définie sur open. Si autoMoveParticipantToBreakoutRoom est défini sur false, utilisez le code suivant pour rejoindre la salle pour petit groupe.

Ceci déclenche l’événement breakoutRoomsUpdated avec la classe JoinBreakoutRoomsEvent qui a la propriété type définie sur join. Vous pouvez utiliser l’instance d’une classe call dans la propriété data pour gérer l’appel de la salle pour petit groupe.

const breakoutRoom = breakoutRoomsFeature.assignedBreakoutRoom;
if(breakoutRoom.state == 'open' && !breakoutRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await breakoutRoom.join();
}

Quand l’utilisateur se trouve dans une salle pour petit groupe et que l’organisateur attribue une nouvelle salle pour petit groupe à l’utilisateur, l’utilisateur reçoit l’événement breakoutRoomsUpdated avec le type assignedBreakoutRooms. Cet événement contient les détails sur la salle pour petit groupe la plus récente. L’utilisateur doit effectuer l’opération hangUp() sur la salle pour petit groupe précédente. Si autoMoveParticipantToBreakoutRoom est défini sur true, l’utilisateur est déplacé automatiquement ; sinon, l’utilisateur doit appeler explicitement la méthode join sur la nouvelle salle pour petit groupe.

//Breakout room which is assigned initially.
const breakoutRoom = breakoutRoomsFeature.assignedBreakoutRoom;
if(breakoutRoom.state == 'open' && !breakoutRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await breakoutRoom.join();
}

// `breakoutRoomsUpdated` event which contains the details of the new breakout room
let assignedRoom = undefined;
const breakoutRoomsUpdatedListener = (event) => {
     switch(event.type) {
          case "assignedBreakoutRooms":
          const assignedRoom = event.data;
          break;
     }
}

if(assignedRoom.threadId != breakoutRoom.threadId && breakoutRooms != null)
{
    await breakoutRoom.hangUp();
}
if(assignedRoom.state == 'open' && !assignedRoom.autoMoveParticipantToBreakoutRoom) {
  const breakoutRoomCall = await assignedRoom.join();
}

L’utilisateur Microsoft 365 disposant d’un rôle Organisateur, Co-organisateur ou Gestionnaire de salles pour petit groupe obtient la liste des salles pour petit groupe créées par le gestionnaire de salles pour petit groupe ou l’organisateur de la réunion principale. Dans ce cas, le comportement est légèrement différent. Cet utilisateur doit appeler explicitement la méthode join() pour rejoindre la salle pour petit groupe. L’utilisateur est initialement maintenu en attente dans la réunion principale, puis il en est finalement supprimé. L’utilisateur doit initialiser la fonctionnalité breakoutRooms pour le breakoutRoomCall afin de recevoir les mises à jour concernant la salle pour petit groupe.

Si l’utilisateur veut rejoindre une des salles pour petit groupe, il appelle explicitement la méthode join.

const breakoutRoom = breakoutRoomsFeature.breakoutRooms[0];
if(breakoutRoom.state == 'open') {
  const breakoutRoomCall = await breakoutRoom.join();
}

Pour quitter une salle pour petit groupe, les utilisateurs doivent exécuter la fonction hangUp() sur l’appel de la salle pour petit groupe. L’utilisateur doit appeler ReturnToMainMeeting pour reprendre l’appel de la réunion principale.

breakoutRoomCall.hangUp();
const mainMeetingCall = breakoutRoomCall.returnToMainMeeting();

Quitter une salle pour petit groupe

Quand l’état de la salle pour petit groupe est closed, l’utilisateur est informé de la fermeture de la salle pour petit groupe via la réception d’événements breakoutRoomsUpdated avec la AssignedBreakoutRoomsEvent classe et la propriété type égales à assignedBreakoutRooms, qui indique que assignedBreakoutRoom a la propriété state définie sur closed. L’utilisateur quitte automatiquement la salle pour petit groupe et peut revenir à la réunion principale en appelant returnToMainMeeting() comme indiqué ci-dessus.

Si l’utilisateur veut quitter la salle pour petit groupe avant sa fermeture et si les paramètres breakoutRoomsFeature.breakoutRoomsSettings de la salle pour petit groupe ont la propriété disableReturnToMainMeeting définie sur false, l’utilisateur peut revenir à l’appel de la réunion principale avec le code suivant :

breakoutRoomCall.hangUp();
const mainMeetingCall = breakoutRoomCall.returnToMainMeeting();

Obtenir les participants de la salle pour petit groupe

Quand vous rejoignez la salle pour petit groupe, vous pouvez utiliser le code suivant pour obtenir la liste des participants distants de la salle pour petit groupe :

const breakoutRoomParticipants = [breakoutRoomCall.remoteParticipants.values()].map((p: SDK.RemoteParticipant) => { p.displayName || p.identifier });
console.log(`Participants of the breakoutRoom : <br/>" + breakoutRoomParticipants.join("<br/>")`);

Arrêter de recevoir les événements des salles pour petit groupe

Utilisez le code suivant pour arrêter de recevoir les événements breakoutRooms.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Propriétés de la salle pour petit groupe

Les salles pour petit groupe ont les propriétés suivantes :

const displayName : string = breakoutRoom.displayName;
const threadId : string = breakoutRoom.threadId;
const state : BreakoutRoomState = breakoutRoom.state;
const autoMoveParticipantToBreakoutRoom : boolean = breakoutRoom.autoMoveParticipantToBreakoutRoom; 
const call : Call | TeamsCall = breakoutRoom.call;
const invitees : Invitee[] = breakoutRoom.invitees;

Paramètres d’une salle pour petit groupe

Les salles pour petit groupe partagent un paramètre qui a les propriétés suivantes :

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;

Dépannage

Étapes suivantes

• Découvrir comment gérer les appels
• Découvrir comment gérer la vidéo
• Découvrez comment enregistrer les appels
• Découvrir comment transcrire les appels