Поделиться через

Комнаты для разбиения

  • Статья

В этой статье описывается, как реализовать комнаты прорыва Microsoft Teams с Службы коммуникации Azure. Эта возможность позволяет Службы коммуникации Azure пользователям в собраниях Teams участвовать в комнатах разбиения. Администраторы Teams управляют доступностью комнат разбиения в собраниях Teams с политикой собраний Teams. Дополнительные сведения о комнатах для разбиения можно найти в документации Teams.

Необходимые компоненты

Только пользователи Microsoft 365 с ролями организатора, соорганизатора или диспетчера комнат останова могут управлять комнатами прорыва.

Поддержка

В следующих таблицах определяется поддержка комнат разбиения в Службы коммуникации Azure.

Удостоверения и типы вызовов

В следующей таблице показана поддержка в комнатах останова для конкретного типа вызова и удостоверения.

Удостоверения Собрание Teams Комната Вызов 1:1 Групповой вызов Вызов взаимодействия Teams 1:1 Вызов взаимодействия с Группами Teams
Пользователь служб коммуникации ✔️
Пользователь Microsoft 365 ✔️

Операции

В следующей таблице показана поддержка отдельных API в вызывающем пакете SDK, связанном с отдельными типами удостоверений.

Операции Пользователь служб коммуникации Пользователь Microsoft 365
Получение назначенной комнаты останова ✔️ ✔️
Получение всех помещений для разбиения ✔️ [1]
Присоединение к помещению для выхода ✔️ ✔️
Управление комнатами разбиения
Участие в чате комнаты для разбиения ✔️ [2]
Получение параметров комнаты для останова ✔️ ✔️

[1] Только пользователь Microsoft 365 с организатором ролей, соорганизатором или диспетчером помещений для разбиения.

[2] Пользователи Microsoft 365 могут использовать API Graph для участия в чате в комнате останова. Идентификатор потока чата предоставляется в назначенном объекте комнаты разбиения.

Пакеты SDK

В следующих таблицах показана поддержка возможностей комнат разбиения в отдельных пакетах SDK Службы коммуникации Azure.

Состояние поддержки Интернет Веб-интерфейс iOS Пользовательский интерфейс iOS Android Пользовательский интерфейс Android Windows
Поддерживается ✔️

Установка пакета SDK

npm install Используйте команду для установки пакета SDK Службы коммуникации Azure Common and Calling SDK для JavaScript:

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

Инициализация обязательных объектов

Экземпляр CallClient требуется для большинства операций вызова. При создании нового CallClient экземпляра его можно настроить с помощью пользовательских параметров, таких как Logger экземпляр.

С помощью экземпляра CallClient можно создать CallAgent экземпляр, вызвав его createCallAgent. Этот метод асинхронно возвращает объект экземпляра CallAgent.

Метод createCallAgent использует CommunicationTokenCredential в качестве аргумента. Он принимает маркер доступа пользователя.

Можно применить метод getDeviceManager для экземпляра CallClient, чтобы получить доступ к 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()

Управление подключением пакета SDK к инфраструктуре Майкрософт

Экземпляр Call Agent помогает управлять вызовами (для присоединения или запуска вызовов). Для работы пакета SDK для вызова необходимо подключиться к инфраструктуре Майкрософт для получения уведомлений о входящих звонках и координации других сведений о вызове. У вас Call Agent есть два возможных состояния:

Подключено — Call Agent значение Connected connectionStatue означает, что клиентский пакет SDK подключен и способен получать уведомления из инфраструктуры Майкрософт.

Отключено — Call Agent значение connectionStatue состояний Disconnected возникает проблема, которая препятствует правильному подключению пакета SDK. Call Agent необходимо повторно создать.

  • invalidToken: если срок действия маркера истек или является недопустимым Call Agent экземпляром, отключается с этой ошибкой.
  • connectionIssue: если возникла проблема с клиентом, подключающимся к инфраструктуре Майкрософт, после многих повторных попыток Call Agent возникает connectionIssue ошибка.

Вы можете проверить, подключен ли локальный сервер Call Agent к инфраструктуре Майкрософт, проверив текущее значение connectionState свойства. Во время активного вызова можно прослушивать connectionStateChanged событие, чтобы определить, изменяются ли Call Agent изменения из подключенного к отключенном состоянию.

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

Реализация помещений для разбиения

BreakoutRoomsfeature— это классCall. Сначала необходимо импортировать пакет Features из пакета SDK для вызовов:

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

Создание компонента breakoutRoom

Затем получите объект API признаков из экземпляра вызова:

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

Подписка на события breakoutRoom

BreakoutRooms API позволяет подписаться на BreakoutRooms события. breakoutRoomsUpdated Событие происходит из экземпляра BreakoutRoomsCallFeature и содержит сведения о созданных, обновленных и назначенных комнатах останова.

Чтобы получить сведения о помещении для разбиения, подпишитесь на breakoutRoomsUpdated событие.

breakoutRoomsFeature.on('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Обработка событий разрывов

Событие breakoutRoomsUpdated предоставляет экземпляр одного из следующих классов в качестве входного параметра. Свойство можно использовать type для различения отдельных типов событий.

  • Класс BreakoutRoomsEvent: это событие активируется, когда пользователь с организатором ролей, соорганизатором или диспетчером комнат для разбиения создает или обновляет комнаты выхода. Пользователи Microsoft 365 с организатором ролей, соорганизатором или диспетчером комнат для разбиения могут получать это событие. Разработчики могут использовать комнаты разбиения в собственности data для просмотра сведений обо всех комнатах разбиения. Этот класс имеет свойство type равно "breakoutRooms".

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

  • Класс BreakoutRoomsSettingsEvent: когда пользователь с организатором ролей, соорганизатором или диспетчером комнат разбиения обновляет параметры комнаты прорыва, он активирует это событие. Разработчики могут использовать эти сведения для отрисовки времени окончания комнаты прорыва или принятия решения о том, следует ли отображать кнопку для присоединения к главной комнате. Этот класс имеет свойство type равно "breakoutRoomSettings".

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

  • Класс AssignedBreakoutRoomsEvent: это событие активируется при назначении пользователем комнаты прорыва или обновлении назначенной комнаты останова. Пользователи могут присоединиться к номеру останова, если для свойства state задано openзначение, оставить комнату прорыва, если для свойства state задано closedзначение , или отобразить сведения о помещении прорыва. Этот класс имеет свойство type равно "assignedBreakoutRoom".

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

  • Класс JoinBreakoutRoomsEvent: это событие активируется при присоединении участника к вызову комнаты прорыва. Это событие может произойти при автоматическом перемещении пользователя в комнату разбиения (тassignedBreakoutRoom. е. если задано state open свойство и trueautoMoveParticipantToBreakoutRoom имеет значение ) или когда пользователь явно присоединяется к комнате разбиения (то есть вызывает метод join в экземпляреassignedBreakoutRoom, если autoMoveParticipantToBreakoutRoom задано falseзначение ). Свойство data содержит экземпляр комнаты call разбиения, который разработчики могут использовать для управления вызовом комнаты разбиения. Этот класс имеет свойство type равно "join".

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

В следующем коде показаны ценные сведения, полученные в событиях комнаты останова:

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

Вывод списка доступных комнат для разбиения

Пользователи Microsoft 365 с организатором ролей, соорганизатором или диспетчером комнат для разбиения могут получить доступ ко всем комнатам выхода.

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

Перечисление приглашений

Пользователь Microsoft 365 с организатором ролей, соорганизатором или диспетчером комнат для останова может получить доступ к участникам, назначенным отдельным комнатам для разбиения.

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

Присоединение к помещению для выхода

assignedBreakoutRoom Если для свойства autoMoveParticipantToBreakoutRoom задано trueзначение , пользователь автоматически перемещается в комнату останова при установке openсвойстваstate. Если autoMoveParticipantToBreakoutRoom задано значение false, используйте следующий код для присоединения к помещению разбиения.

Это активирует событие с классом breakoutRoomsUpdated JoinBreakoutRoomsEvent , который имеет свойство type , заданное как join. Экземпляр класса call в свойстве data можно использовать для управления вызовом комнаты разбиения.

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

Когда пользователь находится в помещении для разбиения, организатор назначает пользователю новую комнату разбиения, пользователь получает breakoutRoomsUpdated событие с типом assignedBreakoutRooms. Это событие содержит последние сведения о помещении для прорыва. Пользователь должен выполнить hangUp() предыдущий вызов комнаты для разбиения. Если autoMoveParticipantToBreakoutRoom задано значение true, пользователь автоматически перемещается, в противном случае пользователю необходимо явно вызвать join метод в новой комнате разбиения.

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

Пользователь Microsoft 365 с организатором ролей, соорганизатором или диспетчером комнат для разбиения можно получить список комнат для разбиения, созданных менеджером комнат для разбиения или организатором основного собрания. В этом случае поведение немного отличается. Этот пользователь должен явно вызвать join() метод для присоединения к комнате разрыва. Пользователь хранится на удержании основного собрания первоначально и в конечном итоге удален из основного собрания. Пользователь должен инициализировать компонент breakoutRooms для breakoutRoomCall получения обновлений в комнате останова.

Если пользователь хочет присоединиться к любому из комнат разбиения, пользователь явно вызывает join метод.

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

Чтобы выйти из комнаты разбиения, пользователи должны выполнить hangUp() функцию в вызове комнаты разбиения. Пользователь будет вызывать ReturnToMainMeeting возобновление основного звонка на собрание.

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

Оставьте комнату для разбиения

Если состояние closedкомнаты прорыва равно, пользователь получает событие breakoutRoomsUpdated с классом AssignedBreakoutRoomsEvent и свойствомtype, равным assignedBreakoutRooms ейclosed, что указывает, assignedBreakoutRoom что имеет значение свойстваstate. Пользователь покидает комнату останова автоматически и может вернуться к главному собранию, вызвав returnToMainMeeting() , как показано выше.

Если пользователь хочет оставить комнату разбиения даже до закрытия комнаты, а параметры breakoutRoomsFeature.breakoutRoomsSettings комнаты выхода имеют свойство disableReturnToMainMeeting , заданное для того, чтобы false пользователь смог вернуться к основному вызову собрания со следующим кодом:

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

Получение участников комнаты прорыва

При присоединении к комнате вы можете использовать следующий код, чтобы получить список удаленных участников комнаты прорыва:

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

Остановка приема событий комнат разбиения

Используйте следующий код, чтобы остановить получение событий разбиения.

breakoutRoomsFeature.off('breakoutRoomsUpdated', breakoutRoomsUpdatedListener);

Свойства комнаты останова

Комнаты для разбиения имеют следующие свойства:

Примечание.

В следующем примере кода эффективно отображаются все свойства комнаты разбиения. Он не предназначен для повторного использования, как показано ниже. На практике вы используете только свойства, необходимые для сценария помещения для разбиения.

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;
Свойства комнаты останова Description
displayName Имя комнаты прорыва. Это свойство доступно только для чтения.
threadId Используйте идентификатор потока чата для присоединения чата к комнате останова. Это свойство доступно только для чтения.
state Состояние комнаты прорыва. Это может быть либо open либо closed. Пользователи смогут присоединиться к комнате прорыва только в том случае, если состояние равно open. Это свойство доступно только для чтения.
autoMoveParticipantToBreakoutRoom Логическое значение, указывающее, перемещаются ли пользователи в комнаты разбиения автоматически, когда state assignedBreakoutRoom задано значение open. Это свойство доступно только для чтения. В параметрах пользовательского интерфейса Teams для комнат разбиения организатор, соорганизатор или диспетчер помещений для разбиения можно настроить этот конкретный параметр. Задав этот параметр, trueучастники автоматически передаются в назначенное место для разбиения. И наоборот, если для этого свойства falseзадано значение, необходимо вручную вызвать join метод для перемещения участников в комнату прорыва.
call Объект вызова комнаты прорыва. Этот объект возвращается, когда пользователь присоединяется к вызову join комнаты разбиения автоматически или путем вызова метода в assignedBreakoutRoom объекте. Это свойство доступно только для чтения.
invitees Список приглашений, назначенных комнате прорыва. Это свойство доступно только для чтения.

Параметры комнаты для останова

Параметр общего доступа к комнатам для разбиения с следующими свойствами:

const disableReturnToMainMeeting : boolean = breakoutRoomsSettings.disableReturnToMainMeeting;
const roomEndTime : TimestampInfo = breakoutRoomsSettings.roomEndTime;
Свойства комнаты останова Description
disableReturnToMainMeeting Отключите участников, чтобы вернуться к главному собранию из вызова комнаты останова. Это свойство доступно только для чтения. В параметрах пользовательского интерфейса Teams для комнат разбиения организатор, соорганизатор или диспетчер комнат для разбиения можно настроить этот конкретный параметр, чтобы управлять тем, когда участник номеров прорыва может вернуться к главному собранию.
roomEndTime Время окончания комнаты для перерыва, заданное пользователем Microsoft 365 с организатором ролей, соорганизатором или диспетчером помещений для разбиения основного собрания. Это свойство доступно только для чтения.

Устранение неполадок

Код ошибки Дополнительный код Категория результатов Причина Разрешение
400 46250 ExpectedError Функция комнат останова доступна только в собраниях Teams. Реализуйте собственный механизм разбиения или используйте собрания Teams.
405 46251 ExpectedError Службы коммуникации Azure в настоящее время отключена эта функция. Попробуйте api в течение нескольких дней.
500 46254 UnexpectedServerError Не удается присоединиться к помещению для разбиения из-за непредвиденной ошибки. Убедитесь, что state assignedBreakoutRoom метод is open и вызывается breakoutRoomsFeature.assignedBreakoutRoom.join() явным образом. Если проблема сохранится, соберите журналы консоли браузера и обратитесь в службу поддержки Службы коммуникации Azure.
500 46255 UnexpectedServerError Не удается провести главное собрание. Убедитесь, что state assignedBreakoutRoom метод is open и вызывается breakoutRoomsFeature.assignedBreakoutRoom.join() явным образом. Если проблема сохранится, соберите журналы консоли браузера и обратитесь в службу поддержки Службы коммуникации Azure.
412 46256 ExpectedError Не удается присоединиться к комнате прорыва, так как комната закрыта. Убедитесь, что state assignedBreakoutRoom метод is open и вызывается breakoutRoomsFeature.assignedBreakoutRoom.join() явным образом.
412 46257 UnexpectedServerError Не удалось возобновить основное собрание. Следуйте инструкциям, определенным в разделе Leave breakout room , чтобы вручную выйти из помещения для разбиения. Если проблема сохранится, соберите журналы консоли браузера и обратитесь в службу поддержки Службы коммуникации Azure.
412 46258 UnexpectedClientError Не удается прочитать сведения о помещении для разбиения. Соберите журналы консоли браузера и обратитесь в службу поддержки Службы коммуникации Azure.
500 46259 UnexpectedServerError Не удалось повесить звонок в комнате прорыва. Следуйте инструкциям, определенным в разделе Leave breakout room , чтобы вручную выйти из помещения для разбиения.
412 46260 UnexpectedClientError Не удается присоединиться к комнате останова, так как она еще не назначена. Убедитесь, что breakoutRoomsFeature.assignedBreakoutRoom у вас есть сведения о назначенной комнате разбиения. Убедитесь, что state assignedBreakoutRoom метод is open и вызывается breakoutRoomsFeature.assignedBreakoutRoom.join() явным образом.
412 46261 UnexpectedClientError Не удается присоединиться к главному собранию. Повторите попытку breakoutRoomsFeature.assignedBreakoutRoom.returnToMainMeeting() , вызвав метод. Если проблема сохранится, соберите журналы консоли браузера и обратитесь в службу поддержки Службы коммуникации Azure.
412 46262 ExpectedError Уже в главном собрании. Вызовите этот метод только в том случае, если участник находится в комнате останова и удален из основного собрания.
412 46263 UnexpectedClientError Сбой существующего вызова комнаты для разбиения. Повторите попытку вызова метода hangup(), чтобы зависнуть вызов. Вызов метода join() для повторного присоединения к комнате останова.

Следующие шаги