在一起模式

發行項
10/04/2024

本文說明如何使用 Azure 通訊服務通話 SDK 來實作Microsoft Teams 共同模式。一起模式可增強虛擬會議和通話，讓他們感覺更個人化。藉由建立統一的檢視，讓所有人置於共用背景，參與者就可以順暢地連線並有效地共同作業。

重要

本文所述的功能目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議用於處理生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
使用者存取令牌以啟用呼叫用戶端。如需詳細資訊，請參閱建立和管理存取權杖。
選擇性：完成快速入門以將語音通話新增至您的應用程式

支援

下表定義在 Azure 通訊服務中共同模式的支援。

身分識別和通話類型

下表顯示呼叫和身分識別類型的支援。

身分識別	Teams 會議	會議室	1:1 通話	群組通話	一對一 Teams Interop 通話	群組 Teams Interop 通話
通訊服務使用者	✔️			✔️		✔️
Microsoft 365 使用者	✔️			✔️		✔️

Operations

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

Operations	通訊服務使用者	Microsoft 365 使用者
啟動一起模式數據流		✔️ [1]
結合模式串流	✔️	✔️
取得場景大小	✔️	✔️
取得座位地圖	✔️	✔️
變更場景
變更座位指派

[1] 只有具有召集人、共同召集人或演示者角色的Microsoft 365 使用者才能呼叫 [一起啟動模式]。

SDK

下表顯示個別 Azure 通訊服務 SDK 中共同模式功能的支援。

平台	Web	Web UI	iOS	iOS UI	Android	Android UI	Windows
受到支援	✔️

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

實作在一起模式

「一起模式」是核心 Call API 的擴充功能。您必須先從呼叫 SDK 匯入呼叫功能：

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

然後，您可以從呼叫實例取得共同模式 API 物件：

const togetherModeFeature = call.feature(Features.TogetherMode);