Együttmód

2025-05-12

Ez a cikk bemutatja, hogyan lehet megvalósítani a Microsoft Teams Together Mode funkciót az Azure Communication Services Calling SDK-k segítségével. A Together Mode javítja a virtuális találkozókat és hívásokat, személyesebbé téve őket. Azáltal, hogy egy egységes nézőpontot hozunk létre, amely mindenkit egy közös háttérbe helyez, a résztvevők zökkenőmentesen kapcsolódhatnak és hatékonyan együttműködhetnek.

Fontos

Az Azure Communication Services ezen funkciója jelenleg előzetes verzióban érhető el. Az előzetes verziójú funkciók nyilvánosan elérhetők, és minden új és meglévő Microsoft-ügyfél használhatja.

Ez az előzetes verzió szolgáltatási szintű megállapodás nélkül kerül biztosításra, és nem javasoljuk, hogy produkciós munkaterhelésekre használják. Előfordulhat, hogy bizonyos funkciók nem támogatottak, vagy a képességek korlátozottak lehetnek.

További információkért lásd: Microsoft Azure Previews Kiegészítő Felhasználási Feltételek.

Támogatás

A következő táblázatok az Azure Communication Services-ben az Együttműködési Módról szóló támogatást határozzák meg.

Azonosítók és hívástípusok

Az alábbi táblázat a hívás- és azonosítástípusok támogatását mutatja be.

Identitások	Teams megbeszélés	Szoba	egyéni hívás	Csoportos hívás	1:1 Teams interoperábilis hívás	"Csapatok közötti együttműködési hívás csoportok számára"
Kommunikációs szolgáltatások felhasználója	✔️			✔️		✔️
Microsoft 365-felhasználó	✔️			✔️		✔️

Műveletek

A következő táblázat bemutatja az egyes API-k támogatását a Calling SDK-ban az egyes személyazonosság típusok szempontjából.

Műveletek	Kommunikációs szolgáltatások felhasználója	Microsoft 365-felhasználó
Indítsa el a Közös Mód streamet		✔️ [1]
Összejövetel mód közvetítés	✔️	✔️
Szerezze be a jelenet méretét	✔️	✔️
Ülőhelytérkép megtekintése	✔️	✔️
Jelenet váltás
Ülésrend módosítása

A "Start Together Mode" csak olyan Microsoft 365 felhasználó által hívható elő, akinek a szerepköre szervező, társszervező vagy előadó.

SDK-k

Az alábbi táblázat az Azure Communication Services SDK-k különálló verzióinak Together Mode funkció támogatottságát mutatja.

Platformok	Világháló	Webes felhasználói felület	Ios	iOS felhasználói felület	Android	Android kezelőfelület (UI)	Windows
Támogatott	✔️

Telepítse az SDK-t

Az npm install parancs használatával telepítheti az Azure Communication Services Common and Calling SDK-t JavaScripthez.

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

Inicializálja a szükséges objektumokat

A legtöbb hívási művelethez egy CallClient példányra van szükség. Amikor új CallClient példányt hozol létre, testreszabott opciókkal konfigurálhatod, mint egy Logger példányt.

A CallClient példány segítségével létrehozhat egy CallAgent példányt a createCallAgent meghívásával. Ez a módszer aszinkron módon egy CallAgent példányobjektumot ad vissza.

A createCallAgent módszer a CommunicationTokenCredential-t használja argumentumként. Elfogad egy felhasználói hozzáférési tokent.

A getDeviceManager metódus használható a CallClient példányon a deviceManager eléréséhez.

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

A Microsoft-infrastruktúrához való SDK-kapcsolat kezelése

A Call Agent példány segít a hívások kezelésében (csatlakozáshoz vagy indításhoz). Ahhoz, hogy működjön, a hívási SDK-nak csatlakoznia kell a Microsoft infrastruktúrájához, hogy értesítéseket kapjon a bejövő hívásokról, és koordinálja a hívás többi részletét. Az ön Call Agent-nek két lehetséges állapota van:

Csatlakoztatva - A Call Agent kapcsolati állapot értéke Connected, ami azt jelenti, hogy a kliens SDK csatlakoztatva van, és képes értesítéseket fogadni a Microsoft infrastruktúrájától.

Disconnected - A Call Agent kapcsolati állapot értéke Disconnected kijelenti, hogy egy olyan probléma van, amely megakadályozza az SDK megfelelő csatlakozását. Call Agent újra létre kell hozni.

invalidToken: Ha egy token lejár vagy érvénytelen, Call Agent példány ezzel a hibával megszakítja a kapcsolatot.
connectionIssue: Ha probléma merül fel az ügyfél Microsoft-infrastruktúrához való csatlakozásával kapcsolatban, többszöri próbálkozás után Call Agent feltárja a connectionIssue hibát.

Ellenőrizheti, hogy a helyi Call Agent csatlakozik-e a Microsoft infrastruktúrához azáltal, hogy megvizsgálja a connectionState tulajdonság aktuális értékét. Aktív hívás közben figyelheti a connectionStateChanged eseményt, hogy meghatározza, vajon a Call Agent állapot Kapcsolódott állapotból Szétkapcsolt állapotba változik-e.

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

Együttműködési mód bevezetése

A Together Mode a Call API kibővített funkciója. Először importálnia kell a hívási funkciókat a Hívási SDK-ból.

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

Ezután megszerezheti a Together Mode API objektumot a hívás példányából.

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

Kapjon értesítéseket, amikor a Társas mód adatfolyama elindul vagy frissül.

Feliratkozhat az eseményre togetherModeStreamsUpdated, hogy értesítéseket kapjon, amikor a Together Mode elindul vagy frissül. Az esemény információkat tartalmaz a hozzáadott videostream megjelenítéséről.

// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] }
togetherModeFeature.on('togetherModeStreamsUpdated', (event) => {
    event.added.forEach(async stream => {
        // stream can be rendered as a remote video stream
    });
});

Összejövetel mód közvetítés

A Together Mode adatfolyamok a togetherModeStream tulajdonságon keresztül érhetők el.

const togetherModeStreams = togetherModeFeature.togetherModeStream;

Az együttes mód streamtulajdonságai	Leírás
`id`	A stream azonosítására használt egyedi szám.
`mediaStreamType`	Visszaadja az Együtt mód adatfolyam típusát. Az érték `mediaStreamType` mindig `video`.
`isReceiving`	Logikai értéket ad vissza, amely jelzi, hogy érkeznek-e videócsomagok.
`size`	Visszaadja a Together módot `StreamSize`, a stream szélességével és magasságával kapcsolatos információkkal pixelben.

Indítsa el az együttműködési módot minden résztvevő számára.

A Microsoft 365 felhasználók, akik szervező, társszervező vagy előadó szerepkörrel rendelkeznek, elkezdhetik az Egymód mindenki számára a találkozón. Amikor a Together mód elindul, az togetherModeStreamsUpdated esemény összes előfizetője értesítést kap, amely lehetővé teszi a résztvevők számára a Together mód megjelenítését.

togetherModeFeature.start();

Együttes mód befejezése

Az Együttes mód automatikusan leáll az összes résztvevő esetében, ha egyetlen résztvevő sem észlel videostreamet egy percig. Nincs API a Together Mode befejezésére.

Szerezze meg a résztvevők koordinátáit az Együtt Módban

Az togetherModeSeatingMap tulajdonság koordinátákat biztosít az áramlat egyes résztvevői számára. A fejlesztők ezeket a koordinátákat használhatják a résztvevők információinak, például a megjelenített névnek vagy a vizuális elemeknek, mint például a reflektorfény, a kézfelemelés és a reakciók, a streamre való ráhelyezéséhez.

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

Jelenet méretének kezelése

A sceneSize tulajdonság meghatározza annak a HTML tárolónak a méreteit (szélesség és magasság), amely a togetherMode videófolyamot tartalmazza. A résztvevők ülőhelyi pozícióit a jelenet méreteinek dimenziói alapján számítják ki. Ha a jelenet mérete nincs megadva, a számítás alapértelmezés szerint 1280 képpont szélességű és 720 képpontos magasságú.

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 )}`)

Események fogadása jelenet- vagy ülésfrissítések esetén

Megjegyzés

Csak a Microsoft 365 felhasználók, akik szervező, társszervező vagy előadó szerepkörben vannak, módosíthatják a jeleneteket vagy a résztvevők kiosztását a Together mód során. Ezeket a változtatásokat csak a Teams kliensből lehet elvégezni.

Ha színváltozás vagy ülésrend változás történik, akkor a togetherModeSceneUpdated vagy togetherModeSeatingUpdated események ennek megfelelően megemelkednek, és frissített számítást nyújtanak a résztvevők üléshelyzetéről.

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

Hibaelhárítás

Kód	Alsókód	Eredménykategória	Indok	Rezolúció
403 hibakód	46303	VárhatóHiba	A résztvevő szerepkörének nincs meg a szükséges engedélye a `togetherMode` start API hívásához.	Csak a Microsoft 365 felhasználók, akik szervezői, társszervezői vagy előadói szereppel rendelkeznek, indíthatják el az "Együtt mód"-ot. Az adott `role` osztály egy példányán keresztül ellenőrizheted egy felhasználó szerepkörét a `Call` tulajdonság segítségével.
403 hibakód	46304	VárhatóHiba	A Together Mode egy nem támogatott hívási helyzetben indult el.	Biztosítsa, hogy a Together Mode csak csoportos hívás vagy meeting helyzetekben legyen elindítva.
403 hibakód	46306	VárhatóHiba	A Together Mode `start` API-t egy Azure Communication Services felhasználó hívta meg.	Csak a Microsoft 365 felhasználók, akik szervezői, társszervezői vagy előadói szereppel rendelkeznek, indíthatják el az "Együtt mód"-ot.