Sdílet prostřednictvím

Oddělené místnosti

  • Článek

Tento článek popisuje, jak implementovat skupinové místnosti Microsoft Teams pomocí Azure Communication Services. Tato funkce umožňuje uživatelům služby Azure Communication Services na schůzkách v Teams účastnit se skupinových místností. Správci Teams řídí dostupnost oddělených místností ve schůzce v Teams pomocí zásad schůzky Teams. Další informace o oddělených místnostech najdete v dokumentaci k Teams.

Požadavky

Skupinové místnosti můžou spravovat jenom uživatelé Microsoftu 365 s organizátorem, spoluorganizátorem nebo rolemi Správce oddělených místností.

Technická podpora

Následující tabulky definují podporu oddělených místností ve službě Azure Communication Services.

Identity a typy volání

Následující tabulka uvádí podporu v oddělených místnostech pro konkrétní typ a identitu volání.

Identity Schůzka v Teams Místnost 1:1 hovor Skupinový hovor 1:1 Zprostředkovatele spolupráce v Teams Skupinový interopový hovor v Teams
Uživatel komunikačních služeb ✔️
Uživatel Microsoftu 365 ✔️

Operace

Následující tabulka ukazuje podporu jednotlivých rozhraní API ve volající sadě SDK související s jednotlivými typy identit.

Operace Uživatel komunikačních služeb Uživatel Microsoftu 365
Získání přiřazené oddělené místnosti ✔️ ✔️
Získání všech skupinových místností ✔️ [1]
Připojit se k oddělené místnosti ✔️ ✔️
Správa skupinových místností
Účast v skupinovém chatu v místnosti ✔️ [2]
Získání nastavení oddělené místnosti ✔️ ✔️

[1] Jenom uživatel Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo správcem oddělené místnosti.

[2] Uživatelé Microsoftu 365 můžou pomocí rozhraní Graph API účastnit se skupinového chatu v místnosti. ID vlákna chatu je k dispozici v přiřazeného objektu oddělené místnosti.

Sady SDK

Následující tabulky ukazují podporu funkce oddělených místností v jednotlivých sadách SDK služby Azure Communication Services.

Stav podpory Web Webové uživatelské rozhraní iOS Uživatelské rozhraní iOS Android Uživatelské rozhraní Androidu Windows
Je podporováno. ✔️

Nainstalujte sadu SDK .

npm install Pomocí příkazu nainstalujte sadu AZURE Communication Services Common and Calling SDK pro JavaScript:

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

Inicializace požadovaných objektů

Pro CallClient většinu operací volání se vyžaduje instance. Když vytvoříte novou CallClient instanci, můžete ji nakonfigurovat s vlastními možnostmi, jako je Logger instance.

CallClient S instancí můžete vytvořit CallAgent instanci voláním createCallAgent. Tato metoda asynchronně vrátí CallAgent objekt instance.

Metoda createCallAgent se používá CommunicationTokenCredential jako argument. Přijímá přístupový token uživatele.

K přístupu deviceManagermůžete použít metodu getDeviceManager v CallClient instanci .

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

Jak nejlépe spravovat připojení sady SDK k infrastruktuře Microsoftu

Tato Call Agent instance vám pomůže spravovat hovory (pro připojení nebo zahájení hovorů). Aby bylo možné pracovat s vaší sadou SDK volání, musí se připojit k infrastruktuře Microsoftu, aby bylo možné dostávat oznámení o příchozích hovorech a koordinovat další podrobnosti volání. Máte Call Agent dva možné stavy:

Připojeno – Call Agent Hodnota connectionStatue znamená, Connected že klientská sada SDK je připojená a dokáže přijímat oznámení z infrastruktury Microsoftu.

Odpojeno – Call Agent Hodnota Disconnected connectionStatue stavů existuje problém, který brání sadě SDK, aby se správně připojil. Call Agent by se mělo znovu vytvořit.

  • invalidToken: Pokud vypršela platnost tokenu nebo je neplatná Call Agent instance, odpojí se s touto chybou.
  • connectionIssue: Pokud došlo k problému s klientem, který se připojuje k infrascture Microsoftu, po mnoha opakovaných pokusech Call AgentconnectionIssue se zobrazí chyba.

Zkontrolujte, jestli je vaše místní Call Agent infrastruktura připojená k infrastruktuře Microsoftu, a to kontrolou aktuální hodnoty connectionState vlastnosti. Během aktivního volání můžete naslouchat connectionStateChanged události a zjistit, jestli Call Agent se změny ze stavu Připojeno k Odpojeno .

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

Implementace oddělených místností

BreakoutRooms je třída featureCall. Nejprve musíte importovat balíček Features z volající sady SDK:

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

Vytvoření funkce BreakoutRoom

Pak získejte objekt rozhraní API funkce z instance volání:

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

Přihlášení k odběru událostí breakoutRoom

Rozhraní BreakoutRooms API umožňuje přihlásit se k odběru BreakoutRooms událostí. Událost breakoutRoomsUpdated pochází z BreakoutRoomsCallFeature instance a obsahuje informace o vytvořených, aktualizovaných a přiřazených oddělených místnostech.

Pokud chcete dostávat podrobnosti o oddělené místnosti, přihlaste se k odběru breakoutRoomsUpdated události.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Zpracování událostí breakoutRoom

Událost breakoutRoomsUpdated poskytuje instanci jedné z následujících tříd jako vstupní parametr. Vlastnost můžete použít type k rozlišení mezi jednotlivými typy událostí.

  • Třída BreakoutRoomsEvent: Tato událost se aktivuje, když uživatel s organizátorem role, spoluorganizátorem nebo správcem oddělené místnosti vytvoří nebo aktualizuje oddělené místnosti. Uživatelé Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo manažerem skupinové místnosti můžou tento typ události přijmout. Vývojáři můžou pomocí oddělených místností ve vlastnosti data vykreslit podrobnosti o všech oddělených místnostech. Tato třída má vlastnost type rovna "breakoutRooms".

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

  • Třída BreakoutRoomsSettingsEvent: Když uživatel s organizátorem role, spoluorganizátorem nebo správcem oddělené místnosti aktualizuje nastavení oddělené místnosti, aktivuje tuto událost. Vývojáři můžou pomocí těchto informací vykreslit čas ukončení skupinové místnosti nebo rozhodnout, jestli se má vykreslit tlačítko pro připojení k hlavní místnosti. Tato třída má vlastnost type rovna "breakoutRoomSettings".

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

  • Třída AssignedBreakoutRoomsEvent: Tato událost se aktivuje, když se uživatel přiřadí k oddělené místnosti nebo se aktualizuje přiřazená oddělená místnost. Uživatelé se můžou připojit k oddělené místnosti, pokud je vlastnost state nastavena na open, opustit oddělenou místnost, pokud je vlastnost state nastavena na closed, nebo vykreslit podrobnosti o oddělené místnosti. Tato třída má vlastnost type rovna "assignedBreakoutRoom".

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

  • Třída JoinBreakoutRoomsEvent: Tato událost se aktivuje, když se účastník připojuje k skupinovému hovoru v místnosti. K této události může dojít, když se uživatel automaticky přesune do oddělené místnosti (to znamená, pokud má vlastnost state nastavenou open na hodnotu a autoMoveParticipantToBreakoutRoom je nastavená truena) nebo když se uživatel explicitně připojí k oddělené místnosti (to znamená volání metody join v instanciassignedBreakoutRoom, pokud autoMoveParticipantToBreakoutRoom je nastavena na false).assignedBreakoutRoom Vlastnost data obsahuje instanci oddělené místnosti call , kterou můžou vývojáři použít k řízení skupinového volání místnosti. Tato třída má vlastnost type rovna "join".

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

Následující kód ukazuje cenné informace přijaté v událostech skupinové místnosti:

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

Seznam dostupných oddělených místností

Uživatelé Microsoftu 365, kteří mají organizátora rolí, spoluorganizátora nebo správce skupinových místností, mají přístup ke všem odděleným místnostem.

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

Seznam pozvaných uživatelů

Uživatel Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo správcem oddělené místnosti může přistupovat k účastníkům přiřazeným k jednotlivým odděleným místnostem.

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

Připojit se k oddělené místnosti

Pokud je vlastnost autoMoveParticipantToBreakoutRoom nastavena assignedBreakoutRoom na true, uživatel se automaticky přesune do oddělené místnosti, když je vlastnost state nastavena na open. Pokud autoMoveParticipantToBreakoutRoom je nastavená hodnota false, použijte následující kód pro připojení k oddělené místnosti.

Tato událost aktivuje breakoutRoomsUpdated událost s třídou JoinBreakoutRoomsEvent , která má vlastnost type nastavena jako join. Instanci třídy call ve vlastnosti data můžete použít ke správě skupinového volání místnosti.

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

Když je uživatel v oddělené místnosti a organizátor přiřadí uživateli novou oddělenou místnost, uživatel získá breakoutRoomsUpdated událost s typem assignedBreakoutRooms. Tato událost obsahuje nejnovější podrobnosti o oddělené místnosti. Uživatel musí provést hangUp() předchozí hovor skupinové místnosti. Pokud autoMoveParticipantToBreakoutRoom je nastavena na true, uživatel se automaticky přesune, jinak uživatel musí volat metodu join explicitně v nové oddělené místnosti.

//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();
}

Uživatel Microsoftu 365 s organizátorem rolí, spoluorganizátorem nebo správcem skupinových místností získá seznam oddělených místností vytvořených manažerem oddělené místnosti nebo organizátorem hlavní schůzky. V tomto případě se chování mírně liší. Tento uživatel musí explicitně volat join() metodu připojení k oddělené místnosti. Uživatel je zpočátku přidržený v hlavní schůzce a nakonec se odebere z hlavní schůzky. Uživatel musí inicializovat funkci breakoutRooms pro breakoutRoomCall pořadí, aby dostával aktualizace v oddělené místnosti.

Pokud se uživatel chce připojit k některé z oddělených místností , pak uživatel explicitně volá metodu join .

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

Aby uživatelé mohli opustit oddělenou místnost, měli by funkci spustit hangUp() při volání skupinové místnosti. Uživatel bude volat ReturnToMainMeeting , aby obnovil hlavní hovor schůzky.

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

Opuštění skupinové místnosti

Když je closedstav oddělené místnosti , uživatel je informován o ukončení skupinové místnosti příjmem události breakoutRoomsUpdated s třídou AssignedBreakoutRoomsEvent a vlastnostítype, která je rovnaassignedBreakoutRooms, která označuje, že assignedBreakoutRoom má vlastnost state nastavenou .closed Uživatel opustí skupinovou místnost automaticky a může se vrátit k hlavní schůzce zavoláním returnToMainMeeting() , jak je znázorněno výše.

Pokud chce uživatel opustit oddělenou místnost i před zavřením místnosti a nastavení breakoutRoomsFeature.breakoutRoomsSettings oddělené místnosti má nastavenou vlastnost disableReturnToMainMeeting , false může se uživatel vrátit do hlavního hovoru schůzky pomocí následujícího kódu:

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

Získání účastníků skupinové místnosti

Když se připojíte k oddělené místnosti, můžete pomocí následujícího kódu získat seznam vzdálených účastníků skupinové místnosti:

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

Ukončení přijímání událostí skupinových místností

Pomocí následujícího kódu ukončete příjem událostí breakoutRooms.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Vlastnosti oddělené místnosti

Oddělené místnosti mají následující vlastnosti:

Poznámka:

Následující ukázkový kód efektivně zobrazí všechny vlastnosti oddělené místnosti. Není určeno k opakovanému použití, jak je znázorněno. V praxi použijete jenom vlastnosti potřebné pro váš scénář skupinové místnosti.

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;
Vlastnosti oddělené místnosti Popis
displayName Název oddělené místnosti. Tato vlastnost je jen ke čtení.
threadId Pomocí ID vlákna chatu se můžete připojit k chatu skupinové místnosti. Tato vlastnost je jen ke čtení.
state Stav skupinové místnosti. Může to být buď open nebo closed. Uživatelé by se mohli připojit k oddělené místnosti pouze v případech, kdy je openstav . Tato vlastnost je jen ke čtení.
autoMoveParticipantToBreakoutRoom Logická hodnota označující, zda jsou uživatelé přesunuti do oddělených místností automaticky, když state je nastavena assignedBreakoutRoom hodnota open. Tato vlastnost je jen ke čtení. V nastavení uživatelského rozhraní Teams pro oddělené místnosti může organizátor, spoluorganizátor nebo správce skupinových místností upravit toto konkrétní nastavení. Nastavením této možnosti se trueúčastníci automaticky převedou do určené oddělené místnosti. Naopak pokud tuto vlastnost nastavíte na false, musíte metodu join ručně zavolat, aby se účastníci přesunuli do oddělené místnosti.
call Objekt skupinového volání místnosti Tento objekt se vrátí, když se uživatel připojí k skupinovému volání místnosti automaticky nebo zavolá metodu join objektu assignedBreakoutRoom . Tato vlastnost je jen ke čtení.
invitees Seznam pozvaných, kteří jsou přiřazeni k oddělené místnosti. Tato vlastnost je jen ke čtení.

Nastavení oddělené místnosti

Nastavení sdílení oddělených místností s následujícími vlastnostmi:

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;
Vlastnosti oddělené místnosti Popis
disableReturnToMainMeeting Zakažte účastníkům návrat na hlavní schůzku z skupinového hovoru v místnosti. Tato vlastnost je jen ke čtení. V nastavení uživatelského rozhraní Teams pro skupinové místnosti může organizátor, spoluorganizátor nebo správce skupinových místností upravit toto konkrétní nastavení tak, aby bylo možné řídit, kdy se účastníci skupinových místností mohou vrátit do hlavní schůzky.
roomEndTime Čas ukončení skupinové místnosti nastavený uživatelem Microsoftu 365 s organizátorem role, spoluorganizátorem nebo správcem oddělené místnosti hlavní schůzky. Tato vlastnost je jen ke čtení.

Řešení problému

Kód chyby Podkód Kategorie výsledků Důvod Rozlišení
400 46250 ExpectedError Funkce Oddělené místnosti je dostupná jenom na schůzkách v Teams. Implementujte vlastní mechanismus skupinové místnosti nebo používejte schůzky Teams.
405 46251 ExpectedError Služba Azure Communication Services tuto funkci aktuálně zakázala. Zkuste rozhraní API za pár dní.
500 46254 UnexpectedServerError Nejde se připojit k oddělené místnosti kvůli neočekávané chybě. Ujistěte se, že stateassignedBreakoutRoom je metoda a open metoda volání breakoutRoomsFeature.assignedBreakoutRoom.join() explicitně. Pokud problém přetrvává, shromážděte protokoly konzoly prohlížeče a obraťte se na podporu služeb Azure Communication Services.
500 46255 UnexpectedServerError Nelze uspořádat hlavní schůzku. Ujistěte se, že stateassignedBreakoutRoom je metoda a open metoda volání breakoutRoomsFeature.assignedBreakoutRoom.join() explicitně. Pokud problém přetrvává, shromážděte protokoly konzoly prohlížeče a obraťte se na podporu služeb Azure Communication Services.
412 46256 ExpectedError Nelze se připojit k oddělené místnosti, protože místnost je uzavřena. Ujistěte se, že stateassignedBreakoutRoom je metoda a open metoda volání breakoutRoomsFeature.assignedBreakoutRoom.join() explicitně.
412 46257 UnexpectedServerError Nejde obnovit hlavní schůzku. Postupujte podle pokynů definovaných v části Leave breakout room pro ruční opuštění oddělené místnosti. Pokud problém přetrvává, shromážděte protokoly konzoly prohlížeče a obraťte se na podporu služeb Azure Communication Services.
412 46258 UnexpectedClientError Podrobnosti o oddělené místnosti nelze přečíst. Shromážděte protokoly konzoly prohlížeče a obraťte se na podporu služeb Azure Communication Services.
500 46259 UnexpectedServerError Hovor skupinové místnosti se nedá zavěsit. Postupujte podle pokynů definovaných v části Leave breakout room pro ruční opuštění oddělené místnosti.
412 46260 UnexpectedClientError Nelze se připojit k oddělené místnosti, protože ještě není přiřazena. Ujistěte se, že breakoutRoomsFeature.assignedBreakoutRoom obsahuje podrobnosti o přiřazené oddělené místnosti. Ujistěte se, že stateassignedBreakoutRoom je metoda a open metoda volání breakoutRoomsFeature.assignedBreakoutRoom.join() explicitně.
412 46261 UnexpectedClientError Nejde se připojit k hlavní schůzce. Zkuste to prosím znovu voláním breakoutRoomsFeature.assignedBreakoutRoom.returnToMainMeeting() metody. Pokud problém přetrvává, shromážděte protokoly konzoly prohlížeče a obraťte se na podporu služeb Azure Communication Services.
412 46262 ExpectedError Už v hlavní schůzce. Tuto metodu zavolejte jenom v případě, že je účastník v oddělené místnosti a odebere se z hlavní schůzky.
412 46263 UnexpectedClientError Existující zablokování skupinové místnosti se nezdařilo. Zkuste znovu zavolat metodu hangup() a zavěsit volání. Volání metody join() pro opětovné připojení k oddělené místnosti.

Další kroky