管理用戶端上的通話錄音

文章
10/23/2024

重要

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

通話錄音可讓使用者錄製其使用 Azure 通訊服務進行的通話。在本文中，您會了解如何管理用戶端上的錄製內容。開始之前，您必須在伺服器端設定錄製。

必要條件

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

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

注意

此 API 僅供開發人員預覽，而且可能會根據收到的意見反應變更。請勿在實際執行環境中使用此 API。若要使用此 API，請使用 Azure 通訊服務通話 Web SDK 的搶鮮版 (Beta) 版本。

雲端錄製

通話錄音是核心 Call API 的擴充功能。您必須先從通話 SDK 匯入通話功能：

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

然後，您可以從呼叫執行個體取得錄製功能 API 物件：

const callRecordingApi = call.feature(Features.Recording);

若要檢查是否正在記錄通話，請檢查 callRecordingApi 的 isRecordingActive 屬性。它會傳回 Boolean。

const isRecordingActive = callRecordingApi.isRecordingActive;

您也可以訂閱以錄製變更：

const isRecordingActiveChangedHandler = () => {
    console.log(callRecordingApi.isRecordingActive);
};

callRecordingApi.on('isRecordingActiveChanged', isRecordingActiveChangedHandler);

您可以使用 callRecordingApi 的 recordings 屬性來取得錄製清單。它會傳 RecordingInfo[]回，其具有雲端錄製的目前狀態。

const recordings = callRecordingApi.recordings;

recordings.forEach(r => {
    console.log("State: ${r.state}");

您也可以訂閱 recordingsUpdated 並取得更新錄製的集合。每當有錄製更新時，就會觸發此事件。

const cloudRecordingsUpdatedHandler = (args: { added: SDK.RecordingInfo[], removed: SDK.RecordingInfo[]}) => {
                        console.log('Recording started by: ');
                        args.added?.forEach(a => {
                            console.log('State: ${a.state}');
                        });

                        console.log('Recording stopped by: ');
                        args.removed?.forEach(r => {
                            console.log('State: ${r.state}');
                        });
                    };
callRecordingApi.on('recordingsUpdated', cloudRecordingsUpdatedHandler );

安裝 SDK

找出您的項目層級build.gradle檔案，並將新增mavenCentral()至和allprojects下的buildscript存放庫清單：

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

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

然後，在您的模組層級 build.gradle 檔案中，將下列幾行新增至 dependencies 區段：

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

初始化必要的物件

若要建立 CallAgent 執行個體，您必須在 CallClient 執行個體上呼叫 createCallAgent 方法。此呼叫會以非同步方式傳回 CallAgent 執行個體物件。

createCallAgent 方法會採用 CommunicationUserCredential 作為引數，用來封裝存取權杖。

若要存取 DeviceManager，您必須先建立 callAgent 執行個體。然後，您可以使用 CallClient.getDeviceManager 方法取得 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();

若要設定來電者的顯示名稱，請使用下列替代方法：

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

錄製通話

注意

此 API 僅供開發人員預覽，而且可能會根據收到的意見反應變更。請勿在實際執行環境中使用此 API。若要使用此 API，請使用 Azure 通訊服務通話 Android SDK 的搶鮮版 (Beta) 版本。

通話錄音是核心 Call 物件的擴充功能。

警告

截至 Azure 通訊服務呼叫 Android SDK 的 1.1.0 版和 Beta 版本 1.1.0-Beta.1 為止，isRecordingActive 和 addOnIsRecordingActiveChangedListener 是 Call 物件的一部分。針對新的搶鮮版 (Beta) 版本，這些 API 已移動為 Call 的擴充功能。

您必須先取得錄製功能物件：

RecordingCallFeature callRecordingFeature = call.feature(Features.RECORDING);

然後，若要檢查是否正在記錄通話，請檢查 callRecordingFeature 的 isRecordingActive 屬性。它會傳回 boolean。

boolean isRecordingActive = callRecordingFeature.isRecordingActive();

您也可以訂閱以錄製變更：

private void handleCallOnIsRecordingChanged(PropertyChangedEvent args) {
  boolean isRecordingActive = callRecordingFeature.isRecordingActive();
}

callRecordingFeature.addOnIsRecordingActiveChangedListener(handleCallOnIsRecordingChanged);

如果您想要從您的應用程式開始錄製，請先遵循通話錄音概觀，以取得設定通話錄音的步驟。

在伺服器上設定通話錄音之後，您需要從 Android 應用程式取得通話的 ServerCallId 值，然後將其傳送至您的伺服器，以開始錄製程序。您可以使用 CallInfo 類別的 getServerCallId()，找到 ServerCallId 值。您可以使用 getInfo()，在類別物件中找到 CallInfo 類別。

try {
    String serverCallId = call.getInfo().getServerCallId().get();
    // Send serverCallId to your recording server to start the call recording.
} catch (ExecutionException | InterruptedException e) {

} catch (UnsupportedOperationException unsupportedOperationException) {

}

當您從伺服器開始錄製時，會觸發事件 handleCallOnIsRecordingChanged，且 callRecordingFeature.isRecordingActive() 的值是 true。

就像開始通話錄音一樣，如果您想要停止通話錄音，您需要取得 ServerCallId，並將其傳送至錄製伺服器，以便其可以停止錄製：

try {
    String serverCallId = call.getInfo().getServerCallId().get();
    // Send serverCallId to your recording server to stop the call recording.
} catch (ExecutionException | InterruptedException e) {

} catch (UnsupportedOperationException unsupportedOperationException) {

}

當您從伺服器停止錄製時，會觸發事件 handleCallOnIsRecordingChanged，且 callRecordingFeature.isRecordingActive() 的值是 false。

設定系統

請遵循下列步驟來設定系統。

建立 Xcode 專案

在 Xcode 中建立新的 iOS 專案，並選取 [單一檢視應用程式] 範本。本文使用 SwiftUI 架構，因此您應該將 Language 設定為 Swift，並將 Interface 設定為 SwiftUI。

您不會在本文中建立測試。您可以隨意清除 [包含測試] 核取方塊。

螢幕擷取畫面：顯示用於在 Xcode 內建立專案的視窗。

使用 CocoaPods 安裝套件和相依性

為您的應用程式建立 Podfile，如以下範例所示：

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

執行 pod install。
使用 Xcode 開啟 .xcworkspace。

要求存取麥克風

若要存取裝置的麥克風，您必須使用 NSMicrophoneUsageDescription 更新應用程式的資訊屬性清單。將相關聯的值設定為對話框中所包含的字串，系統用來要求使用者存取權。

以滑鼠右鍵按一下專案樹狀結構的 Info.plist 項目，接著選取 [開啟為]>[原始程式碼]。將以下幾行新增至最上層 <dict> 區段中，然後儲存檔案。

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

設定應用程式架構

開啟項目的 ContentView.swift 檔案。將 import 宣告新增至檔案頂端，以匯入 AzureCommunicationCalling 程式庫。此外，匯入 AVFoundation。您需要它才能在程式代碼中要求音訊許可權。

import AzureCommunicationCalling
import AVFoundation

初始化 CallAgent

若要從 CallClient 建立 CallAgent 執行個體，您必須使用 callClient.createCallAgent 方法，在 CallAgent 物件初始化後以非同步方式傳回該物件。

若要建立通話用戶端，請傳遞 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 物件傳遞至 CallClient，並設定顯示名稱：

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

錄製通話

注意

此 API 僅供開發人員預覽，而且可能會根據收到的意見反應變更。請勿在實際執行環境中使用此 API。若要使用此 API，請使用 Azure 通訊服務通話 iOS SDK 的搶鮮版 (Beta) 版本。

通話錄音是核心 Call 物件的擴充功能。

警告

截至 Azure 通訊服務呼叫 iOS SDK 的 1.1.0 版和 Beta 版本 1.1.0-Beta.1 為止，isRecordingActive 是 Call 物件的一部分，而 didChangeRecordingState 是 CallDelegate 委派的一部分。針對新的搶鮮版 (Beta) 版本，這些 API 已移動為 Call 的擴充功能。

您必須先取得錄製功能物件：

let callRecordingFeature = call.feature(Features.recording)

然後，若要檢查是否正在記錄通話，請檢查 callRecordingFeature 的 isRecordingActive 屬性。它會傳回 Bool。

let isRecordingActive = callRecordingFeature.isRecordingActive;

您也可以使用事件 didChangeRecordingState 在類別上實作 RecordingCallFeatureDelegate 委派來訂閱錄製變更：

callRecordingFeature.delegate = self

// didChangeRecordingState is a member of RecordingCallFeatureDelegate
public func recordingCallFeature(_ recordingCallFeature: RecordingCallFeature, didChangeRecordingState args: PropertyChangedEventArgs) {
    let isRecordingActive = recordingFeature.isRecordingActive
}

如果您想要從您的應用程式開始錄製，請先遵循通話錄音概觀，以取得設定通話錄音的步驟。

在伺服器上設定通話錄音之後，您需要從 iOS 應用程式取得通話的 ServerCallId 值，然後將其傳送至您的伺服器，以開始錄製程序。您可以使用 CallInfo 類別的 getServerCallId()，找到 ServerCallId 值。您可以使用 getInfo()，在類別物件中找到 CallInfo 類別。

// Send serverCallId to your recording server to start the call recording.
let serverCallId = call.info.getServerCallId(){ (serverId, error) in }

當您從伺服器開始錄製時，會觸發事件 didChangeRecordingState，且 recordingFeature.isRecordingActive 的值是 true。

就像開始通話錄音一樣，如果您想要停止通話錄音，您需要取得 ServerCallId，並將其傳送至錄製伺服器，以便其可以停止錄製：

// Send serverCallId to your recording server to stop the call recording.
let serverCallId = call.info.getServerCallId(){ (serverId, error) in }

當您從伺服器停止錄製時，會觸發事件 didChangeRecordingState，且 recordingFeature.isRecordingActive 的值是 false。

設定系統

請遵循下列步驟來設定系統。

建立 Visual Studio 專案

針對通用 Windows 平台應用程式，請在 Visual Studio 2022 中建立新的空白應用程式（通用 Windows） 專案。在輸入專案名稱之後，隨意選擇高於 10.0.17763.0 的任何 Windows SDK。

針對 WinUI 3 應用程式，使用空白應用程式、封裝 (桌面中的 WinUI 3) 範本建立新專案，以設定單頁 WinUI 3 應用程式。需要 Windows App SDK 1.3 版或更新版本。

使用 NuGet 套件管理員來安裝套件和相依性

通話 SDK API 和程式庫可透過 NuGet 套件公開取得。

若要尋找、下載並安裝呼叫 SDK NuGet 套件：

藉由選取 [工具]>[NuGet 套件管理員]>[管理解決方案的 NuGet 套件]，開啟 NuGet 套件管理員。
選取 [ 瀏覽]，然後在搜尋方塊中輸入 Azure.Communication.Calling.WindowsClient 。
請確定 已選取 [包含發行前版本 ] 複選框。
選取 Azure.Communication.Calling.WindowsClient 套件，然後選取 [Azure.Communication.Calling.WindowsClient 1.4.0-beta.1] 或更新版本。
選取對應至右窗格上 Azure 通訊服務項目的複選框。
選取 [安裝]。

錄製通話

通話錄音是核心 Call 物件的擴充功能。您必須先取得錄製功能物件：

RecordingCallFeature recordingFeature = call.Features.Recording;

然後，若要檢查是否正在記錄通話，請檢查 recordingFeature 的 IsRecordingActive 屬性。它會傳回 boolean。

boolean isRecordingActive = recordingFeature.IsRecordingActive;

您也可以訂閱以錄製變更：

private async void Call__OnIsRecordingActiveChanged(object sender, PropertyChangedEventArgs args)
  boolean isRecordingActive = recordingFeature.IsRecordingActive;
}

recordingFeature.IsRecordingActiveChanged += Call__OnIsRecordingActiveChanged;

合規性錄製

合規性錄製是以 Microsoft Teams 原則為基礎的錄製。您可以使用本教學課程加以啟用：通話的 Teams 原則型錄製簡介。

原則型錄製會在有原則的使用者加入通話時自動啟動。若要從 Azure 通訊服務取得有關錄製的通知，請使用下列程式碼：

const callRecordingApi = call.feature(Features.Recording);

const isComplianceRecordingActive = callRecordingApi.isRecordingActive;

const isComplianceRecordingActiveChangedHandler = () => {
    console.log(callRecordingApi.isRecordingActive);
};

callRecordingApi.on('isRecordingActiveChanged', isComplianceRecordingActiveChangedHandler);

您也可以使用自訂錄製 Bot 來實作合規性錄製。請參閱 GitHub 範例。

分享方式：

管理用戶端上的通話錄音

必要條件

安裝 SDK

初始化必要的物件

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

雲端錄製

安裝 SDK

初始化必要的物件

錄製通話

設定系統

建立 Xcode 專案

使用 CocoaPods 安裝套件和相依性

要求存取麥克風

設定應用程式架構

初始化 CallAgent

錄製通話

設定系統

建立 Visual Studio 專案

使用 NuGet 套件管理員來安裝套件和相依性

錄製通話

合規性錄製

下一步

意見反映

更多資源