Condividi tramite


Gruppi di lavoro

Questo articolo descrive come implementare le breakout room di Microsoft Teams con Servizi di comunicazione di Azure. Questa funzionalità consente agli utenti di Servizi di comunicazione di Azure nelle riunioni di Teams di partecipare alle sale di breakout. Gli amministratori di Teams controllano la disponibilità delle sale di interruzione nelle riunioni di Teams con i criteri delle riunioni di Teams. È possibile trovare altre informazioni sulle breakout room nella documentazione di Teams.

Prerequisiti

Solo gli utenti di Microsoft 365 con ruoli organizzatore, co-organizzatore o responsabile di breakout room possono gestire le breakout room.

Supporto tecnico

Le tabelle seguenti definiscono il supporto delle breakout room in Servizi di comunicazione di Azure.

Identità e tipi di chiamata

Nella tabella seguente viene illustrato il supporto nelle sale di interruzione per un tipo di chiamata e un'identità specifici.

Identità Riunione di Teams Club 1:1 Chiamata Chiamata di gruppo Chiamata di interoperabilità di Teams 1:1 Chiamata di interoperabilità di Teams di gruppo
Utente di Servizi di comunicazione ✔️
Utente di Microsoft 365 ✔️

Operazioni

La tabella seguente illustra il supporto per le singole API nell'SDK chiamante correlato ai singoli tipi di identità.

Operazioni Utente di Servizi di comunicazione Utente di Microsoft 365
Ottenere tutte le breakout room assegnate ✔️ ✔️
Ottenere tutte le breakout room ✔️[1]
Unirsi a una breakout room ✔️ ✔️
Gestire le sale breakout
Partecipare alla chat di breakout room ✔️[2]
Ottenere le impostazioni della breakout room ✔️ ✔️

[1] Solo un utente di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile di breakout room.

[2] Gli utenti di Microsoft 365 possono usare l'API Graph per partecipare alla chat della breakout room. L'ID thread della chat viene fornito nell'oggetto breakout room assegnata.

SDK

Le tabelle seguenti illustrano il supporto per la funzionalità delle sale di interruzione in singoli SDK Servizi di comunicazione di Azure.

Stato del supporto Web Interfaccia utente Web iOS Interfaccia utente iOS Android Interfaccia utente Android Finestre
Supportato ✔️

Installazione dell'SDK

Usare il comando npm install per installare SDK comuni e di chiamata di Servizi di comunicazione di Azure per JavaScript:

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

Inizializzare gli oggetti necessari

Per la maggior parte delle operazioni di chiamata è necessaria un'istanza di CallClient. Quando si crea una nuova istanza di CallClient, è possibile configurarla con opzioni personalizzate come un'istanza di Logger.

Con l'istanza di CallClient è possibile creare un'istanza di CallAgent chiamando il createCallAgent. Questo metodo restituisce in modo asincrono un oggetto istanza CallAgent.

Il metodo createCallAgent usa CommunicationTokenCredential come argomento. Accetta un token di accesso utente.

È possibile usare il metodo getDeviceManager nell'istanza di CallClient per accedere a 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()

Come gestire al meglio la connettività dell'SDK all'infrastruttura Microsoft

L'istanza Call Agent consente di gestire le chiamate (per partecipare o avviare le chiamate). Per lavorare con l'SDK per chiamate, è necessario connettersi all'infrastruttura Microsoft per ricevere notifiche delle chiamate in arrivo e coordinare altri dettagli delle chiamate. Call Agent ha due possibili stati:

Connesso : un valore connectionStatue Call Agent di Connected indica che l'SDK client è connesso e in grado di ricevere notifiche dall'infrastruttura Microsoft.

Disconnesso : un valore connectionStatue Call Agent di Disconnected indica un problema che impedisce all'SDK di connettersi correttamente. Call Agent deve essere ricreato.

  • invalidToken: se un token è scaduto o non è valido l'istanza Call Agent si disconnette con questo errore.
  • connectionIssue: se si verifica un problema con il client che si connette a Microsoft infrascture, dopo molti tentativi Call Agent espone l'errore connectionIssue.

È possibile verificare se l'infrastruttura locale Call Agent è connessa all'infrastruttura Microsoft controllando il valore corrente della proprietà connectionState. Durante una chiamata attiva è possibile restare in ascolto dell'evento connectionStateChanged per determinare se Call Agent cambia dallo stato Connesso a Disconnesso.

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);

Implementare le sale di interruzione

BreakoutRooms è un feature della classe Call. Prima di tutto, è necessario importare il pacchetto Features dall’SDK Chiamata:

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

Creare una funzionalità breakoutRoom

Ottenere quindi l'oggetto API della funzionalità dall'istanza di chiamata:

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

Sottoscrivere a eventi breakoutRoom

L'API BreakoutRooms consente di sottoscrivere a eventi BreakoutRooms. Un breakoutRoomsUpdated evento proviene da un'istanza BreakoutRoomsCallFeature di e contiene informazioni sulle sale di interruzione create, aggiornate e assegnate.

Per ricevere dettagli sulla sala di interruzione, sottoscrivere all'evento breakoutRoomsUpdated.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Gestire eventi breakoutRoom

L'evento breakoutRoomsUpdated fornisce un'istanza di una delle classi seguenti come parametro di input. È possibile utilizzare la proprietà type per distinguere tra singoli tipi di evento.

  • Classe BreakoutRoomsEvent: questo evento viene attivato quando un utente con l'organizzatore del ruolo, il co-organizzatore o il responsabile della sala di interruzione crea o aggiorna le sale di interruzione. Gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile sala breakout possono ricevere questo tipo di evento. Gli sviluppatori possono usare le sale di interruzione nella proprietà data per eseguire il rendering dei dettagli su tutte le breakout room. Questa classe ha una proprietà type uguale a "breakoutRooms".

      export interface BreakoutRoomsEvent {
        /**
         * Breakout room event type
        */
        type: "breakoutRooms",
        /**
         * list of Breakout rooms
        */
        data: BreakoutRoom[] | undefined;
      }
    
  • Classe BreakoutRoomsSettingsEvent: quando un utente con un organizzatore del ruolo, un co-organizzatore o un responsabile della sala di interruzione aggiorna le impostazioni della sala di interruzione, attiva questo evento. Gli sviluppatori possono usare queste informazioni per eseguire il rendering dell'ora in cui termina la sala di interruzione o decidere se eseguire il rendering di un pulsante per partecipare alla sala principale. Questa classe ha una proprietà type uguale a "breakoutRoomSettings".

      export interface BreakoutRoomSettingsEvent {
        /**
        * Breakout room event type
        */
        type: "breakoutRoomSettings",
        /**
        * Breakout Room setting details
        */
        data: BreakoutRoomSettings | undefined;
      }
    
  • Classe AssignedBreakoutRoomsEvent: questo evento viene attivato quando l'utente viene assegnato a una breakout room o la breakout room assegnata viene aggiornata. Gli utenti possono partecipare alla sala di interruzione quando la proprietà state è impostata su open, lasciare la sala di interruzione quando la proprietà state è impostata su closedo visualizzare i dettagli della sala di interruzione. Questa classe ha una proprietà type uguale a "assignedBreakoutRoom".

      export interface AssignedBreakoutRoomEvent {
        /**
         * Breakout room event type
         */
        type: "assignedBreakoutRoom";
        /**
         * Assigned breakout room details
         */
        data: BreakoutRoom | undefined;
      }
    
  • Classe JoinBreakoutRoomsEvent: questo evento viene attivato quando il partecipante partecipa a una chiamata alla sala di interruzione. Questo evento può verificarsi quando un utente viene spostato automaticamente nella sala di interruzione, ovvero se assignedBreakoutRoom la proprietà state è impostata su e autoMoveParticipantToBreakoutRoom è impostata open su ) o quando un utente partecipa in modo esplicito a una sala di interruzione, ovvero chiama il metodo join nell'istanza assignedBreakoutRoom quando autoMoveParticipantToBreakoutRoom è impostato truesu false. La proprietà data contiene l'istanza della breakout room call, può essere usata dagli sviluppatori per controllare la chiamata della breakout room. Questa classe ha una proprietà type uguale a "join".

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

Il codice seguente mostra preziose informazioni ricevute negli eventi della breakout room:

    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);

Elencare le breakout room disponibili

Gli utenti di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile sala breakout possono accedere a tutte le sale di breakout.

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

Elencare gli inviti

Un utente di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile di breakout room può accedere ai partecipanti assegnati a singole breakout room.

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

Unirsi a una breakout room

Se assignedBreakoutRoom ha la proprietà autoMoveParticipantToBreakoutRoom impostata su true, l'utente viene automaticamente spostato nella breakout room quando la proprietà state è impostata su open. Se autoMoveParticipantToBreakoutRoom è impostato su false, usare il codice seguente per unirsi alla breakout room.

Questo attiva l'evento breakoutRoomsUpdated con la classe JoinBreakoutRoomsEvent che ha la proprietà type impostata su join. È possibile usare l'istanza di una classe call nella proprietà data per gestire la chiamata alla sala di breakout room.

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

Quando l'utente si trova in una sala di interruzione e l'organizzatore assegna una nuova sala breakout all'utente, l'utente ottiene breakoutRoomsUpdated l'evento con il tipo assignedBreakoutRooms. Questo evento contiene i dettagli più recenti della sala di interruzione. L'utente deve effettuare una precedente chiamata alla hangUp() sala di interruzione. Se autoMoveParticipantToBreakoutRoom è impostato su true, l'utente viene spostato automaticamente; in caso contrario, l'utente deve chiamare il join metodo in modo esplicito nella nuova sala di interruzione.

//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'utente di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile sala breakout ottiene l'elenco delle sale breakout create dal responsabile della sala breakout o dall'organizzatore della riunione principale. In questo caso, il comportamento è leggermente diverso. Questo utente deve chiamare join() in modo esplicito il metodo per partecipare alla sala di interruzione. L'utente viene tenuto in attesa nella riunione principale inizialmente e infine rimosso dalla riunione principale. L'utente deve inizializzare la funzionalità breakoutRoom per l'ordine breakoutRoomCall in cui ricevere gli aggiornamenti nella sala di interruzione.

Se l'utente vuole partecipare a una delle sale di interruzione, l'utente chiama in modo esplicito il join metodo .

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

Per uscire da una sala di interruzione, gli utenti devono eseguire la hangUp() funzione nella chiamata alla sala di interruzione. L'utente sta chiamando ReturnToMainMeeting per riprendere la chiamata alla riunione principale.

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

Lasciare la breakout room

Quando lo stato della sala di interruzione è closed, l'utente viene informato sulla fine della sala di interruzione ricevendo un evento breakoutRoomsUpdated con classe AssignedBreakoutRoomsEvent e proprietà uguale a assignedBreakoutRooms che indica che assignedBreakoutRoom la proprietà type state è impostata su closed. L'utente lascia automaticamente la sala di interruzione e può tornare alla riunione principale chiamando returnToMainMeeting() come illustrato in precedenza.

Se l'utente vuole lasciare la sala di interruzione anche prima che la sala venga chiusa e le impostazioni della sala di interruzione abbiano la breakoutRoomsFeature.breakoutRoomsSettings proprietà disableReturnToMainMeeting impostata su false , l'utente può tornare alla chiamata alla riunione principale con il codice seguente:

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

Ottenere i partecipanti della breakout room

Quando ci si unisce alla breakout room, è possibile usare il codice seguente per ottenere l'elenco dei partecipanti in remoto della breakout room:

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

Interrompere la ricezione degli eventi di breakout room

Usare il codice seguente per interrompere la ricezione di eventi breakoutRoom.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Proprietà della breakout room

Le breakout room hanno le proprietà seguenti:

Nota

Nel codice di esempio seguente vengono visualizzate in modo efficiente tutte le proprietà della sala di interruzione. Non è destinato a essere riutilizzato come illustrato. In pratica si usano solo le proprietà necessarie per lo scenario della sala di interruzione.

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;
Proprietà della breakout room Descrizione
displayName Nome della sala di interruzione. Questa proprietà è di sola lettura.
threadId Usare l'ID del thread di chat per partecipare alla chat della sala di interruzione. Questa proprietà è di sola lettura.
state Stato della sala di interruzione. Può essere open o closed. Gli utenti potranno partecipare alla sala di interruzione solo quando lo stato è open. Questa proprietà è di sola lettura.
autoMoveParticipantToBreakoutRoom Valore booleano che indica se gli utenti vengono spostati automaticamente nelle sale di interruzione quando l'oggetto state di assignedBreakoutRoom è impostato su open. Questa proprietà è di sola lettura. Nelle impostazioni dell'interfaccia utente di Teams per le breakout room, l'organizzatore, il co-organizzatore o il responsabile della breakout room possono modificare questa impostazione specifica. Impostando questa opzione su true, i partecipanti vengono trasferiti automaticamente nella sala di interruzione designata. Viceversa, se si imposta questa proprietà su false, è necessario chiamare manualmente il join metodo per spostare i partecipanti nella sala di interruzione.
call Oggetto call room breakout. Questo oggetto viene restituito quando l'utente unisce automaticamente la chiamata alla sala di interruzione o chiamando il metodo sull'oggetto join assignedBreakoutRoom . Questa proprietà è di sola lettura.
invitees Elenco di invitati assegnati alla sala di interruzione. Questa proprietà è di sola lettura.

Impostazioni della breakout room

Le breakout room condividono l'impostazione con le proprietà seguenti:

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;
Proprietà della breakout room Descrizione
disableReturnToMainMeeting Disabilitare i partecipanti per tornare alla riunione principale dalla chiamata alla sala di interruzione. Questa proprietà è di sola lettura. Nelle impostazioni dell'interfaccia utente di Teams per le breakout room, l'organizzatore, il co-organizzatore o il responsabile della breakout room può modificare questa impostazione specifica per controllare quando il partecipante delle breakout room possa tornare alla riunione principale.
roomEndTime Ora di fine sala breakout impostata dall'utente di Microsoft 365 con ruolo organizzatore, co-organizzatore o responsabile sala breakout della riunione principale. Questa proprietà è di sola lettura.

Risoluzione dei problemi

Codice errore Codice secondario Categoria dei risultati Motivo Risoluzione
400 46250 ExpectedError La funzionalità Breakout Room è disponibile solo nelle riunioni di Teams. Implementare un meccanismo di breakout room personalizzato o usare le riunioni di Teams.
405 46251 ExpectedError Attualmente, Servizi di comunicazione di Azure ha disabilitato questa funzionalità. Provare le API tra qualche giorno.
500 46254 UnexpectedServerError Impossibile unirsi alla breakout room a causa di un errore imprevisto. Assicurarsi che il state di assignedBreakoutRoom sia open e chiamare il metodo breakoutRoomsFeature.assignedBreakoutRoom.join() in modo esplicito. Se il problema persiste, raccogliere i log della console del browser e contattare il supporto di Servizi di comunicazione di Azure.
500 46255 UnexpectedServerError Impossibile mettere in attesa la riunione principale. Assicurarsi che il state di assignedBreakoutRoom sia open e chiamare il metodo breakoutRoomsFeature.assignedBreakoutRoom.join() in modo esplicito. Se il problema persiste, raccogliere i log della console del browser e contattare il supporto di Servizi di comunicazione di Azure.
412 46256 ExpectedError Non è possibile partecipare alla breakout room perché è chiusa. Assicurarsi che il state di assignedBreakoutRoom sia open e chiamare il metodo breakoutRoomsFeature.assignedBreakoutRoom.join() in modo esplicito.
412 46257 UnexpectedServerError Impossibile riprendere la riunione principale. Seguire le istruzioni definite nella sezione Leave breakout room per uscire manualmente dalla breakout room. Se il problema persiste, raccogliere i log della console del browser e contattare il supporto di Servizi di comunicazione di Azure.
412 46258 UnexpectedClientError Impossibile leggere i dettagli della breakout room. Raccogliere i log della console del browser e contattare il supporto di Servizi di comunicazione di Azure.
500 46259 UnexpectedServerError Impossibile terminare la chiamata della breakout room. Seguire le istruzioni definite nella sezione Leave breakout room per uscire manualmente dalla breakout room.
412 46260 UnexpectedClientError Impossibile partecipare alla breakout room perché non è stata ancora assegnata. Assicurarsi che l'oggetto breakoutRoomsFeature.assignedBreakoutRoom abbia i dettagli della breakout room assegnata. Assicurarsi che il state di assignedBreakoutRoom sia open e chiamare il metodo breakoutRoomsFeature.assignedBreakoutRoom.join() in modo esplicito.
412 46261 UnexpectedClientError Impossibile partecipare alla riunione principale. Riprovare chiamando il breakoutRoomsFeature.assignedBreakoutRoom.returnToMainMeeting() metodo . Se il problema persiste, raccogliere i log della console del browser e contattare il supporto di Servizi di comunicazione di Azure.
412 46262 ExpectedError Già nella riunione principale. Chiama questo metodo solo quando il partecipante si trova nella sala di interruzione e rimosso dalla riunione principale.
412 46263 UnexpectedClientError Il blocco della chiamata alla sala di interruzione esistente non è riuscito. Provare a chiamare di nuovo il metodo hangup() per appendere la chiamata. Chiama il metodo join() per partecipare di nuovo alla sala di interruzione.

Passaggi successivi