分組會議室

本文說明如何使用 Azure 通訊服務 實作 Microsoft Teams 分組討論室。 此功能可讓 Teams 會議中的 Azure 通訊服務 用戶參與分組會議室。 Teams 系統管理員可控制 Teams 會議中與 Teams 會議原則的分組會議室可用性。 您可以在 Teams 文件中找到關於分組討論區的額外資訊。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 請參閱 免費建立帳戶。
• 已部署通訊服務資源。 請參閱 建立通訊服務資源。
• 用來啟用呼叫用戶端的使用者存取權杖。 如需詳細資訊，請參閱建立和管理存取權杖。
• Teams 會議召集人必須指派可啟用分組會議室的Teams會議原則。 請參閱 Teams會議原則。
• 選擇性：完成快速入門，將 語音通話新增至您的應用程式。

只有具有召集人、共同召集人或分組討論區管理員角色的 Microsoft 365 使用者才能管理分組討論區。

支援

下表定義 Azure 通訊服務中分組討論區的支援。

身分識別和通話類型

下表顯示特定通話類型和身分識別的分組室支援。

Operations

下表顯示呼叫SDK中與個別身分識別類型相關的個別 API 支援。

[1] 僅具有角色召集人、共同召集人或分組討論區管理員的 Microsoft 365 使用者。

[2] Microsoft 365 使用者可以使用圖形 API 參與分組討論區聊天。 聊天對話識別碼會在指派的分組討論區物件中提供。

SDK

下表顯示個別 Azure 通訊服務 SDK 中分組室功能的支援。

安裝 SDK

使用 npm install 命令，安裝適用於 JavaScript 的 Azure 通訊服務通用和通話 SDK：

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

初始化必要的物件

大部分通話作業都需要 CallClient 執行個體。 當您建立新的 CallClient 執行個體時，您可以使用自訂選項加以設定，如同 Logger 執行個體一樣。

使用 CallClient 執行個體，您可以藉由呼叫 createCallAgent 來建立 CallAgent 執行個體。 此方法會以非同步的方式傳回 CallAgent 執行個體物件。

createCallAgent 方法會使用 CommunicationTokenCredential 作為引數。 其接受使用者存取權杖。

您可以使用 CallClient 執行個體上的 getDeviceManager 方法來存取 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()

如何最好地管理與 Microsoft 基礎結構的 SDK 連線

Call Agent 執行個體可協助您管理通話 (加入或啟動通話)。 若要運作，您的通話 SDK 必須連線到 Microsoft 基礎結構以取得來電通知，並協調其他通話詳細資料。 您的 Call Agent 有兩種可能的狀態：

已連線 - Connected 的 Call Agent connectionStatue 值表示用戶端 SDK 已連線且能夠接收來自 Microsoft 基礎結構的通知。

已中斷連線 - Disconnected 狀態的 Call Agent connectionStatue 值指出有問題導致 SDK 無法正確連線。 Call Agent 應該重新建立。

• invalidToken：如果權杖已過期或無效，Call Agent 執行個體會中斷連線，並出現此錯誤。
• connectionIssue：如果用戶端連線到 Microsoft 基礎結構時發生問題，在多次重試之後，Call Agent 會公開 connectionIssue 錯誤。

您可以藉由檢查 connectionState 屬性的目前值，檢查本機 Call Agent 是否已連線到 Microsoft 基礎結構。 在作用中通話期間，您可以接聽 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);

實作分組室

BreakoutRooms 是 類別 Call 的 feature。 首先，您需要從呼叫 SDK 匯入套件 Features：

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

處理 breakoutRoom 事件

事件 breakoutRoomsUpdated 提供下列其中一個類別的實例做為輸入參數。 您可以使用 type 屬性來區分單一事件類型。

• 類別 BreakoutRoomsEvent：當具有角色召集人、共同召集人或分組室管理員的使用者建立或更新分組室時，就會觸發此事件。 Microsoft 365 位具有角色召集人、共同召集人或分組會議室管理員的使用者可以接收這種類型的活動。 開發人員可以使用 data 屬性中的分組討論區來轉譯所有討論區的詳細資料。 這個類別具有等同於 "breakoutRooms" 的 type 屬性。

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

• 類別 BreakoutRoomsSettingsEvent：具有角色召集人、共同召集人或分組會議室管理員的使用者更新分會室的設定時，它會觸發此事件。 開發人員可以使用這項資訊來轉譯分拆室結束的時間，或決定是否要轉譯按鈕以加入主會議室。 這個類別具有等同於 "breakoutRoomSettings" 的 type 屬性。

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

• 類別 AssignedBreakoutRoomsEvent：當使用者指派給分組討論區或指派的分組討論區更新時，就會觸發此事件。 當 屬性 state 設定為 open時，使用者可以加入分組室、將屬性 state 設定 closed為 時離開分組室，或轉譯分組室的詳細數據。 這個類別具有等同於 "assignedBreakoutRoom" 的 type 屬性。

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

• 類別 JoinBreakoutRoomsEvent：當參與者加入分組會議室通話時，就會觸發此事件。 當使用者自動移至分拆室時，就會發生此事件（也就是說，如果 assignedBreakoutRoom 屬性設定為 open 且autoMoveParticipantToBreakoutRoom設定為 true），或當使用者明確加入分組室時 （也就是說，當 設定為 時autoMoveParticipantToBreakoutRoomfalse，在 實例assignedBreakoutRoom上呼叫 方法joinstate）。 data 屬性包含分組討論區 call 執行個體，開發人員可用來控制分組討論區通話。 這個類別具有等同於 "join" 的 type 屬性。

    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 具有 設定為 true 的 autoMoveParticipantToBreakoutRoom 屬性，則當 state 屬性設定為 open 時，使用者會自動移動至分組討論區。 如果 autoMoveParticipantToBreakoutRoom 設定為 false，請使用下列程式碼來加入分組討論區。

這會觸發具有設定為 join type 屬性的 JoinBreakoutRoomsEvent 類別 breakoutRoomsUpdated 事件。 您可以在 data 屬性中使用 call 類別的執行個體來管理分組討論區通話。

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 inorder 在分組室接收更新。

如果使用者想要加入任何分組室，則用戶會明確呼叫 join 方法。

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

若要結束分組室，用戶應該在分組室呼叫上執行 函 hangUp() 式。 使用者將會呼叫 ReturnToMainMeeting 以繼續主要會議通話。

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

離開分組討論區

當分組室狀態為 closed時，使用者會收到類別和 屬性type等於 assignedBreakoutRooms 的事件breakoutRoomsUpdatedAssignedBreakoutRoomsEvent，告知使用者分界室的結尾，指出 assignedBreakoutRoom 屬性state已設定為 closed。 用戶會自動離開分會場，並可以呼叫 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/>")`);

停止接收分組討論區事件

使用下列程式代碼停止接收 BreakoutRooms 事件。

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;

分組討論區設定

具有下列屬性的分組討論區共用設定：

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

疑難排解

下一步

• 了解如何管理通話
• 了解如何管理視訊
• 了解如何錄製通話
• 了解如何轉譯通話