Wyświetlanie stanu transkrypcji wywołań na kliencie

Artykuł
04/01/2025

Zanim będziesz mógł transkrybować uczestników, musisz zebrać zgodę wszystkich uczestników rozmowy. Usługa Microsoft Teams umożliwia użytkownikom rozpoczęcie transkrypcji w spotkaniach lub połączeniach. Zdarzenie będzie wyświetlane po rozpoczęciu transkrypcji. Możesz sprawdzić stan transkrypcji, jeśli transkrypcja została uruchomiona przed dołączeniem do rozmowy lub spotkania. Możesz wyrazić jawną zgodę na transkrypcję, jeśli spotkanie lub rozmowa tego wymagają, i już ją zebrałeś.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Wdrożony zasób usług komunikacyjnych. Utwórz zasób usług komunikacyjnych.
Token dostępu użytkownika umożliwiający włączenie klienta wywołującego. Aby uzyskać więcej informacji, zobacz Tworzenie tokenów dostępu i zarządzanie nimi.
Opcjonalnie: ukończ przewodnik szybkiego startu, aby dodawać połączenia głosowe do swojej aplikacji

Wsparcie

W poniższych tabelach zdefiniowano obsługę transkrypcji wywołań w usługach Azure Communication Services.

Tożsamości i typy wywołań

W poniższych tabelach przedstawiono obsługę transkrypcji dla określonego typu wywołania i tożsamości.

Tożsamości	Spotkanie Teams	Pokój	Połączenie 1:1	Rozmowa grupowa	1:1 Połączenie międzyoperacowe usługi Teams	Połączenie interoperacyjne Grupy Teams
Użytkownik usług komunikacyjnych	✔️				✔️	✔️
Użytkownik platformy Microsoft 365	✔️				✔️	✔️

Operacje

W poniższych tabelach przedstawiono obsługę poszczególnych interfejsów API w ramach zestawu SDK dla poszczególnych typów tożsamości.

Operacje	Użytkownik usług komunikacyjnych	Użytkownik platformy Microsoft 365
Otrzymanie informacji o rozpoczęciu transkrypcji zdarzenia	✔️	✔️
Uzyskiwanie stanu transkrypcji	✔️	✔️
Uruchamianie lub zatrzymywanie transkrypcji
Dowiedz się, czy wymagana jest jawna zgoda	✔️ [1]	✔️ [1]
Wyraź zgodę na transkrypcję	✔️ [1]	✔️ [1]

[1] Ta funkcja jest dostępna tylko w przypadku spotkań usługi Teams i grupowych wywołań współdziałania usługi Teams.

Zestawy SDK

W poniższych tabelach przedstawiono obsługę transkrypcji w poszczególnych zestawach SDK usług Azure Communication Services.

Platformy	Internet	Interfejs użytkownika sieci Web	iOS	Interfejs użytkownika systemu iOS	Android	Interfejs użytkownika systemu Android	Windows
Jest wspierana	✔️	✔️ [1]	✔️ [1]	✔️ [1]	✔️ [1]	✔️ [1]	✔️ [1]

[1] Te zestawy SDK nie obsługują jawnej zgody.

Instalacja zestawu SDK

Użyj polecenia npm install, aby zainstalować platformę Azure Communication Services Common oraz Calling SDK dla języka JavaScript.

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

Inicjowanie wymaganych obiektów

Wystąpienie CallClient jest wymagane w przypadku większości operacji wywołania. Podczas tworzenia nowego wystąpienia CallClient, można je skonfigurować za pomocą opcji niestandardowych, podobnie jak wystąpienie Logger.

Za pomocą instancji CallClient, można utworzyć instancję CallAgent, wywołując metodę createCallAgent. Metoda ta asynchronicznie zwraca wystąpienie obiektu CallAgent.

Metoda createCallAgent używa CommunicationTokenCredential jako argumentu. Akceptuje token dostępu użytkownika.

Można użyć metody getDeviceManager na wystąpieniu CallClient, aby uzyskać dostęp do 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()

Jak najlepiej zarządzać łącznością zestawu SDK z infrastrukturą firmy Microsoft

Wystąpienie Call Agent pomaga zarządzać wywołaniami (aby dołączyć lub uruchomić wywołania). Aby można było pracować z zestawem SDK wywołującym, należy połączyć się z infrastrukturą firmy Microsoft, aby otrzymywać powiadomienia o połączeniach przychodzących i koordynować inne szczegóły połączeń. Twój Call Agent ma dwa możliwe stany:

Połączono — Call Agent wartość Connected connectionStatue oznacza, że zestaw SDK klienta jest połączony i może odbierać powiadomienia z infrastruktury firmy Microsoft.

Rozłączone — Wartość Disconnected statusu połączenia Call Agent wskazuje na problem uniemożliwiający prawidłowe nawiązanie połączenia z SDK. Call Agent należy utworzyć ponownie.

invalidToken: Jeśli token wygasł lub jest nieprawidłowy, Call Agent wystąpienie rozłącza się z tym błędem.
connectionIssue: jeśli występuje problem z połączeniem klienta z infrastrukturą firmy Microsoft, po wielu ponownych próbach Call Agent uwidacznia błąd connectionIssue.

Możesz sprawdzić, czy środowisko lokalne Call Agent jest połączone z infrastrukturą firmy Microsoft, sprawdzając bieżącą connectionState wartość właściwości. Podczas aktywnej rozmowy można nasłuchiwać zdarzenia connectionStateChanged, aby określić, czy Call Agent zmienia się ze stanu Połączono na Odłączone.

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

Ostrzeżenie

Ze względu na zmiany w usłudze Microsoft Teams zestawy SDK wywołujące JavaScript w wersjach 1.21 i niższych zatrzymują transkrypcję w Teams i blokują użytkownikom Teams rozpoczęcie transkrypcji. Jeśli chcesz korzystać z transkrypcji usługi Teams w wywołaniach i spotkaniach, musisz uaktualnić zestaw SDK połączeń do co najmniej wersji 1.22.

Transkrypcja rozmowy telefonicznej

Transcription jest rozszerzoną funkcją klasy Call. Najpierw należy uzyskać obiekt funkcji transkrypcji z interfejsu API.

const callTranscriptionFeature = call.feature(Features.Transcription);

Stan transkrypcji można sprawdzić we właściwości isTranscriptionActive. Jeśli wartość jest ustawiona na true, transkrypcja jest aktywna.

const isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive;

Możesz subskrybować zdarzenie, które jest wyzwalane po zmianie stanu transkrypcji:

const isTranscriptionActiveChangedHandler = () => {
  console.log(callTranscriptionFeature.isTranscriptionActive);
};
callTranscriptionFeature.on('isTranscriptionActiveChanged', isTranscriptionActiveChangedHandler);

Możesz anulować subskrypcję zdarzenia przy użyciu następującego kodu:

callTranscriptionFeature.off('isTranscriptionActiveChanged', isTranscriptionActiveChangedHandler);

Jeśli spotkanie lub połączenie usługi Teams jest skonfigurowane tak, aby wymagać wyraźnej zgody na nagrywanie lub transkrypcję, musisz zebrać jawną zgodę od użytkowników, aby umożliwić użytkownikom transkrypcję lub rejestrowanie. Możesz aktywnie wyrazić zgodę podczas dołączania do spotkania lub reaktywnie po rozpoczęciu nagrywania lub transkrypcji. Dopóki nie zostanie udzielona jawna zgoda, udostępnianie dźwięku, wideo i ekranu uczestników zostanie wyłączone podczas transkrypcji.

Możesz sprawdzić, czy transkrypcja spotkania wymaga jawnej zgody na podstawie właściwości isTeamsConsentRequired. Jeśli wartość jest ustawiona na true, wymagana jest jawna zgoda dla call.

const isTranscriptionConsentRequired = callTranscriptionFeature.isTeamsConsentRequired;

Jeśli masz już zgodę użytkownika na transkrypcję, możesz wywołać metodę grantTeamsConsent() , aby wskazać jawną zgodę na usługę. Ta zgoda jest ważna tylko dla jednej call sesji, a użytkownicy muszą ponownie wyrazić zgodę, jeśli ponownie dołączą do spotkania.

callTranscriptionFeature.grantTeamsConsent();

Usiłowania włączenia udostępniania dźwięku, wideo lub ekranu nie powiodą się, gdy transkrypcja jest aktywna; wymagana jest wyraźna zgoda, która nie została jeszcze udzielona. Tę sytuację można rozpoznać, sprawdzając właściwość reason klasy pod kątem ParticipantCapabilitiesi turnVideoOnunmuteMic.shareScreen Te możliwości można znaleźć w funkcji call.feature(Features.Capabilities). Te możliwości będą podawać powód ExplicitConsentRequired, ponieważ użytkownicy muszą wyrazić jawną zgodę.

Instalacja zestawu SDK

Znajdź plik build.gradle projektu i dodaj mavenCentral() do listy repozytoriów w obszarze buildscript i allprojects na poziomie projektu.

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

Następnie w pliku na poziomie modułu build.gradle dodaj następujące wiersze do sekcji dependencies:

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-calling:1.0.0'
    ...
}

Inicjowanie wymaganych obiektów

Aby utworzyć CallAgent wystąpienie, należy wywołać metodę createCallAgent na wystąpieniu CallClient. To wywołanie zwraca asynchronicznie obiekt instancji CallAgent.

Metoda createCallAgent przyjmuje CommunicationUserCredential jako argument, który hermetyzuje token dostępu.

Aby uzyskać dostęp do DeviceManager, należy najpierw utworzyć instancję callAgent. Następnie możesz użyć metody CallClient.getDeviceManager, aby uzyskać DeviceManager.

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

Aby ustawić nazwę wyświetlaną elementu wywołującego, użyj tej alternatywnej metody:

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

Ostrzeżenie

Do wersji 1.1.0 oraz wersji beta 1.1.0-beta.1, zestaw SDK do wywołań na system Android w usługach Azure Communication Services miał isTranscriptionActive i addOnIsTranscriptionActiveChangedListener jako część obiektu Call. W przypadku nowych wersji beta te interfejsy API zostały przeniesione jako rozszerzona funkcja Call, zgodnie z opisem poniżej.

Transkrypcja wywołań jest rozszerzoną funkcją obiektu podstawowego Call . Najpierw należy uzyskać obiekt funkcji transkrypcji:

TranscriptionCallFeature callTranscriptionFeature = call.feature(Features.TRANSCRIPTION);

Następnie, aby sprawdzić, czy połączenie jest przepisywane, skontroluj właściwość . Zwraca wartość boolean.

boolean isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive();

Możesz również subskrybować zmiany w transkrypcji:

private void handleCallOnIsTranscriptionChanged(PropertyChangedEvent args) {
    boolean isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive();
}

callTranscriptionFeature.addOnIsTranscriptionActiveChangedListener(handleCallOnIsTranscriptionChanged);

Konfigurowanie systemu

Wykonaj następujące kroki, aby skonfigurować system.

Tworzenie projektu Xcode

W programie Xcode utwórz nowy projekt systemu iOS i wybierz szablon Aplikacja z jednym widokiem. W tym artykule jest używana struktura SwiftUI, dlatego należy ustawić wartość Language na Swift i ustawić wartość Interface na SwiftUI.

Nie zamierzasz tworzyć testów w tym artykule. Możesz śmiało wyczyścić pole wyboru Uwzględnij testy.

Zrzut ekranu przedstawiający okno tworzenia projektu w programie Xcode.

Instalowanie pakietu i zależności przy użyciu narzędzia CocoaPods

Utwórz plik Podfile dla aplikacji, podobnie jak w tym przykładzie:

platform :ios, '13.0'
use_frameworks!
target 'AzureCommunicationCallingSample' do
    pod 'AzureCommunicationCalling', '~> 1.0.0'
end

Uruchom program pod install.
Otwórz .xcworkspace za pomocą programu Xcode.

Żądanie dostępu do mikrofonu

Aby uzyskać dostęp do mikrofonu urządzenia, należy zaktualizować listę właściwości informacji aplikacji przy użyciu polecenia NSMicrophoneUsageDescription. Ustaw skojarzoną wartość na ciąg zawarty w oknie dialogowym używanym przez system do proszenia użytkownika o dostęp.

Kliknij prawym przyciskiem myszy na wpisie Info.plist w drzewie projektu, a następnie wybierz pozycję Otwórz jako>Kod źródłowy. Dodaj następujące wiersze w sekcji najwyższego poziomu <dict> , a następnie zapisz plik.

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

Konfigurowanie struktury aplikacji

Otwórz plik projektu ContentView.swift . Dodaj deklarację import na początku pliku, aby zaimportować bibliotekę AzureCommunicationCalling . Ponadto zaimportuj plik AVFoundation. Potrzebujesz tego do zapytań o pozwolenie na dźwięk w kodzie.

import AzureCommunicationCalling
import AVFoundation

Inicjowanie CallAgent

Aby utworzyć CallAgent wystąpienie z CallClient, należy użyć metody callClient.createCallAgent, która zwraca asynchronicznie obiekt CallAgent po zainicjowaniu.

Aby utworzyć klienta wywołania, przekaż obiekt CommunicationTokenCredential.

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

CommunicationTokenCredential Przekaż utworzony obiekt do CallClient, a następnie ustaw nazwę wyświetlaną:

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

Ostrzeżenie

Do wersji 1.1.0 i beta w wersji 1.1.0-beta.1 Azure Communication Services Calling iOS SDK, isTranscriptionActive jest częścią obiektu Call, a didChangeTranscriptionState jest częścią delegata CallDelegate. W przypadku nowych wersji beta te interfejsy API zostały przeniesione jako rozszerzona funkcja Call, dokładnie tak jak opisano poniżej.

Transkrypcja wywołań jest rozszerzoną funkcją obiektu podstawowego Call . Najpierw należy uzyskać obiekt funkcji transkrypcji:

let callTranscriptionFeature = call.feature(Features.transcription)

Następnie, aby sprawdzić, czy rozmowa została przetranskrybowana, sprawdź isTranscriptionActive właściwość callTranscriptionFeature. Zwraca wartość Bool.

let isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive;

Możesz również subskrybować zmiany transkrypcji, implementując TranscriptionCallFeatureDelegate delegata w klasie za pomocą zdarzenia didChangeTranscriptionState:

callTranscriptionFeature.delegate = self

// didChangeTranscriptionState is a member of TranscriptionCallFeatureDelegate
public func transcriptionCallFeature(_ transcriptionCallFeature: TranscriptionCallFeature, didChangeTranscriptionState args: PropertyChangedEventArgs) {
    let isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive
}

Konfigurowanie systemu

Wykonaj następujące kroki, aby skonfigurować system.

Tworzenie projektu programu Visual Studio

Dla aplikacji na Uniwersalną platformę Windows w programie Visual Studio 2022, utwórz nowy projekt Pusta aplikacja (Windows uniwersalny). Po wprowadzeniu nazwy projektu możesz wybrać dowolny zestaw Windows SDK nowszy niż 10.0.17763.0.

W przypadku aplikacji WinUI 3 utwórz nowy projekt z szablonem Blank App, Packaged (WinUI 3 in Desktop), aby skonfigurować jednostronicową aplikację WinUI 3. Wymagany jest zestaw Windows App SDK w wersji 1.3 lub nowszej.

Instalowanie pakietu i zależności przy użyciu Menedżer pakietów NuGet

Interfejsy API i biblioteki Calling SDK są publicznie dostępne za pośrednictwem pakietu NuGet.

Aby znaleźć, pobrać i zainstalować pakiet NuGet wywołań SDK:

Otwórz Menedżer pakietów NuGet, wybierając pozycję >> Zarządzanie pakietami NuGet dla rozwiązania.
Wybierz pozycję Przeglądaj, a następnie wprowadź ciąg Azure.Communication.Calling.WindowsClient w polu wyszukiwania.
Upewnij się, że pole wyboru Uwzględnij wersję wstępną zostało zaznaczone.
Wybierz pakiet Azure.Communication.Calling.WindowsClient, a następnie wybierz pozycję Azure.Communication.Calling.WindowsClient1.4.0-beta.1 lub nowszą wersję.
Zaznacz pole wyboru odpowiadające projektowi usług Azure Communication Services w okienku po prawej stronie.
Wybierz Zainstaluj.

Transkrypcja wywołań jest rozszerzoną funkcją obiektu podstawowego Call . Najpierw należy uzyskać obiekt funkcji transkrypcji:

TranscriptionCallFeature transcriptionFeature = call.Features.Transcription;

Następnie, aby sprawdzić, czy połączenie jest transkrybowane, należy skontrolować właściwość IsTranscriptionActive elementu transcriptionFeature. Zwraca wartość boolean.

boolean isTranscriptionActive = transcriptionFeature.isTranscriptionActive;

Możesz również subskrybować zmiany w transkrypcji:

private async void Call__OnIsTranscriptionActiveChanged(object sender, PropertyChangedEventArgs args)
    boolean isTranscriptionActive = transcriptionFeature.IsTranscriptionActive();
}

transcriptionFeature.IsTranscriptionActiveChanged += Call__OnIsTranscriptionActiveChanged;

Zgodność zestawu SDK

W poniższej tabeli przedstawiono minimalną wersję zestawów SDK, które obsługują poszczególne interfejsy API.

Operacje	Internet	Interfejs użytkownika sieci Web	iOS	Interfejs użytkownika systemu iOS	Android	Interfejs użytkownika systemu Android	Windows
Uzyskaj informację, że transkrypcja wydarzenia się rozpoczęła	1.0.0, 1.25.3-beta.1	1.0.0, 1.0.0-beta.8	2.1.0, 2.1.0-beta.1	1.0.0, 1.0.0-beta.8	1.1.0, 1.2.0-beta.1	1.0.0, 1.0.0-beta.8	1.0.0, 1.0.0-beta.31
Uzyskiwanie stanu transkrypcji	1.0.0, 1.25.3-beta.1	1.0.0, 1.0.0-beta.8	2.1.0, 2.1.0-beta.1	1.0.0, 1.0.0-beta.8	1.1.0, 1.2.0-beta.1	1.0.0, 1.0.0-beta.8	1.0.0, 1.0.0-beta.31
Dowiedz się, czy wymagana jest jawna zgoda	1.31.2, 1.32.1-beta.1	❌	❌	❌	❌	❌	❌
Udzielenie wyraźnej zgody na rejestrowanie	1.31.2, 1.32.1-beta.1	❌	❌	❌	❌	❌	❌

Udostępnij za pośrednictwem

Wyświetlanie stanu transkrypcji wywołań na kliencie

Wymagania wstępne

Wsparcie

Tożsamości i typy wywołań

Operacje

Zestawy SDK

Instalacja zestawu SDK

Inicjowanie wymaganych obiektów

Jak najlepiej zarządzać łącznością zestawu SDK z infrastrukturą firmy Microsoft

Transkrypcja rozmowy telefonicznej

Instalacja zestawu SDK

Inicjowanie wymaganych obiektów

Konfigurowanie systemu

Tworzenie projektu Xcode

Instalowanie pakietu i zależności przy użyciu narzędzia CocoaPods

Żądanie dostępu do mikrofonu

Konfigurowanie struktury aplikacji

Inicjowanie CallAgent

Konfigurowanie systemu

Tworzenie projektu programu Visual Studio

Instalowanie pakietu i zależności przy użyciu Menedżer pakietów NuGet

Zgodność zestawu SDK

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Wyświetlanie stanu transkrypcji wywołań na kliencie

Wymagania wstępne

Wsparcie

Tożsamości i typy wywołań

Operacje

Zestawy SDK

Instalacja zestawu SDK

Inicjowanie wymaganych obiektów

Jak najlepiej zarządzać łącznością zestawu SDK z infrastrukturą firmy Microsoft

Transkrypcja rozmowy telefonicznej

Jawna zgoda

Instalacja zestawu SDK

Inicjowanie wymaganych obiektów

Konfigurowanie systemu

Tworzenie projektu Xcode

Instalowanie pakietu i zależności przy użyciu narzędzia CocoaPods

Żądanie dostępu do mikrofonu

Konfigurowanie struktury aplikacji

Inicjowanie CallAgent

Konfigurowanie systemu

Tworzenie projektu programu Visual Studio

Instalowanie pakietu i zależności przy użyciu Menedżer pakietów NuGet

Zgodność zestawu SDK

Następne kroki

Opinia

Dodatkowe zasoby