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
- Un account Azure con una sottoscrizione attiva. Vedere Creare gratuitamente un account.
- Una risorsa di Servizi di comunicazione distribuita. Vedere Creare una risorsa di Servizi di comunicazione.
- Token di accesso utente per abilitare il client chiamante. Per altre informazioni, vedere Creare e gestire i token di accesso.
- L'organizzatore delle riunioni di Teams deve assegnare i criteri di riunione di Teams che consentono le sale di interruzione. Vedere Criteri riunione di Teams.
- Facoltativo: completare la guida introduttiva per aggiungere chiamate vocali all'applicazione.
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'istanzaCall Agent
si disconnette con questo errore.connectionIssue
: se si verifica un problema con il client che si connette a Microsoft infrascture, dopo molti tentativiCall Agent
espone l'erroreconnectionIssue
.
È 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 suopen
, lasciare la sala di interruzione quando la proprietàstate
è impostata suclosed
o 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 seassignedBreakoutRoom
la proprietàstate
è impostata su eautoMoveParticipantToBreakoutRoom
è impostataopen
su ) o quando un utente partecipa in modo esplicito a una sala di interruzione, ovvero chiama il metodojoin
nell'istanzaassignedBreakoutRoom
quandoautoMoveParticipantToBreakoutRoom
è impostatotrue
sufalse
. La proprietàdata
contiene l'istanza della breakout roomcall
, 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. |