在一起模式
本文說明如何使用 Azure 通訊服務 通話 SDK 來實作 Microsoft Teams 共同模式。 一起模式可增強虛擬會議和通話,讓他們感覺更個人化。 藉由建立統一的檢視,讓所有人置於共用背景,參與者就可以順暢地連線並有效地共同作業。
重要
本文所述的功能目前處於公開預覽狀態。 此預覽版本沒有服務等級協定,不建議用於處理生產工作負載。 可能不支援特定功能,或可能已經限制功能。 如需詳細資訊,請參閱 Microsoft Azure 預覽版增補使用條款。
下表定義在 Azure 通訊服務 中共同模式的支援。
下表顯示呼叫和身分識別類型的支援。
身分識別 | Teams 會議 | 會議室 | 1:1 通話 | 群組通話 | 一對一 Teams Interop 通話 | 群組 Teams Interop 通話 |
---|---|---|---|---|---|---|
通訊服務使用者 | ✔️ | ✔️ | ✔️ | |||
Microsoft 365 使用者 | ✔️ | ✔️ | ✔️ |
下表顯示呼叫SDK中個別 API 對個別身分識別類型的支援。
Operations | 通訊服務使用者 | Microsoft 365 使用者 |
---|---|---|
啟動一起模式數據流 | ✔️ [1] | |
結合模式串流 | ✔️ | ✔️ |
取得場景大小 | ✔️ | ✔️ |
取得座位地圖 | ✔️ | ✔️ |
變更場景 | ||
變更座位指派 |
[1] 只有具有召集人、共同召集人或演示者角色的Microsoft 365 使用者才能呼叫 [一起啟動模式]。
下表顯示個別 Azure 通訊服務 SDK 中「共同模式」功能的支援。
平台 | Web | Web UI | iOS | iOS UI | Android | Android UI | Windows |
---|---|---|---|---|---|---|---|
受到支援 | ✔️ |
使用 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()
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);
「一起模式」是核心 Call
API 的擴充功能。 您必須先從呼叫 SDK 匯入呼叫功能:
import { Features} from "@azure/communication-calling";
然後,您可以從呼叫實例取得共同模式 API 物件:
const togetherModeFeature = call.feature(Features.TogetherMode);
您可以訂閱事件 togetherModeStreamsUpdated
,以在 [一起模式] 啟動或更新時接收通知。 事件包含轉譯已新增視訊串流的相關信息。
// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] }
togetherModeFeature.on('togetherModeStreamsUpdated', (event) => {
event.added.forEach(async stream => {
// stream can be rendered as a remote video stream
});
});
您可以透過 屬性 togetherModeStream
來存取 [一起模式] 資料流。
const togetherModeStreams = togetherModeFeature.togetherModeStream;
一起模式數據流屬性 | 描述 |
---|---|
id |
用來識別數據流的唯一數位。 |
mediaStreamType |
傳回 [一起模式] 數據流類型。 的值 mediaStreamType 一律 video 為 。 |
isReceiving |
傳回布爾值,指出是否收到視訊封包。 |
size |
傳回 [一起模式 StreamSize ],其中包含以像素為單位之數據流寬度和高度的相關信息。 |
Microsoft 365 位具有角色召集人、共同召集人或演示者的用戶可以在會議中為每個人啟動共同模式。 當 [一起模式] 啟動時,事件接收通知的所有訂閱者 togetherModeStreamsUpdated
都會讓參與者轉譯在一起模式。
togetherModeFeature.start();
如果任何參與者在一分鐘內未偵測到任何參與者的視訊串流,[一起模式] 會自動終止。 沒有 API 可結束在一起模式。
屬性 togetherModeSeatingMap
會為數據流中的個別參與者提供座標。 開發人員可以使用這些座標來重迭參與者資訊,例如顯示名稱或視覺功能,例如焦點、手舉和串流上的反應。
// returns Map<string, TogetherModeSeatingPosition>
// where the key is the participant ID
// and value of type TogetherModeSeatingPosition is the position relative to the sceneSize
// TogetherModeSeatingPosition {
// top: number;
// left: number;
// width: number;
// height: number;
// }
const seatingMap = togetherModeFeature.togetherModeSeatingMap;
屬性 sceneSize
會指定裝載 togetherMode
視訊串流之 HTML 容器的維度(寬度和高度)。 參與者的座位位置是根據場景大小的維度來計算。 如果未提供場景大小,計算預設為寬度為 1,280 像素,高度為 720 圖元。
const togetherModeContainerSize = { width: 500, height: 500 };
// To set the scene size
togetherModeFeature.sceneSize = togetherModeContainerSize;
// To get the scene size
console.log(`Current scene has the following size: ${JSON.stringify(togetherModeFeature.sceneSize )}`)
注意
只有Microsoft 365 位具有角色召集人、共同召集人或演示者的使用者,才能變更一起模式中參與者的場景或指派。 這些變更只能從Teams客戶端進行。
如果有場景變更或座位變更,則會 togetherModeSceneUpdated
分別引發 或 togetherModeSeatingUpdated
事件,並提供參與者座位位置的更新計算。
const seatUpdate = (participantSeatingMap) => {
participantSeatingMap.forEach((participantID, seatingCoordinates) => {
console.log(`User with ID: ${participantID} has new coordinates ${JSON.stringify(seatingCoordinates)} `)
})
}
togetherModeFeature.on('togetherModeSceneUpdated', seatUpdate);
togetherModeFeature.on('togetherModeSeatingUpdated', seatUpdate);
代碼 | 子代碼 | 結果類別 | 原因 | 解決方法 |
---|---|---|---|---|
403 | 46303 | ExpectedError | 參與者的角色沒有呼叫 togetherMode 啟動 API 的必要許可權。 |
只有具有角色召集人、共同召集人或演示者的 365 位使用者Microsoft才能啟動 [共同模式]。 您可以透過 role 類別實例 Call 上的 屬性來檢查使用者的角色。 |
403 | 46304 | ExpectedError | 在不支援的呼叫案例中啟動一起模式。 | 請確定只有在群組通話或會議案例中才啟動 [共同模式]。 |
403 | 46306 | ExpectedError | Azure 通訊服務 使用者一起呼叫的模式 start API。 |
只有具有角色召集人、共同召集人或演示者的 365 位使用者Microsoft才能啟動 [共同模式]。 |