你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

观察用户的功能

我是否有权打开视频？是否有权打开麦克风？是否有权共享屏幕？ 这些权限是参与者可用功能的一些示例，可以通过功能 API 来了解。 了解这些功能有助于构建用户界面，该用户界面仅显示与本地用户有权执行的操作相关的按钮。

先决条件

• 具有活动订阅的 Azure 帐户。 免费创建帐户。
• 已部署的通信服务资源。 创建通信服务资源。
• 用于启用通话客户端的用户访问令牌。 有关详细信息，请参阅创建和管理访问令牌。
• 可选：完成快速入门向应用程序添加语音呼叫

安装 SDK

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务通用 SDK 和通话 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()

如何最好地管理 SDK 与 Microsoft 基础结构的连接性

Call Agent 实例可帮助你管理通话（以加入或启动通话）。 通话 SDK 需要连接到 Microsoft 基础结构以获取传入通话通知并协调其他通话详细信息，否则无法工作。 你的 Call Agent 有两种可能的状态：

已连接 - Call Agent connectionStatue 值为 Connected 表示客户端 SDK 已连接，能够接收来自 Microsoft 基础结构的通知。

已断开连接 - Call Agent connectionStatue 值为 Disconnected 表示存在阻止 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 的扩展功能，支持在当前通话中获取本地参与者的功能。

此功能支持注册事件侦听器，以侦听功能更改。

注册“功能”功能：

const capabilitiesFeature = this.call.feature(Features.Capabilities);

获取本地参与者的功能：Capabilities 对象具有本地参与者的功能，并且类型为 ParticipantCapabilities。 Capabilities 的属性包括：

• isPresent 指示是否存在功能。
• reason 指示功能解决原因。

const capabilities =  capabilitiesFeature.capabilities;

订阅 capabilitiesChanged 事件：

capabilitiesFeature.on('capabilitiesChanged', (capabilitiesChangeInfo) => {
    for (const [key, value] of Object.entries(capabilitiesChangeInfo.newValue)) {
        if(key === 'turnVideoOn' && value.reason != 'FeatureNotSupported') {
             (value.isPresent) ? this.setState({ canOnVideo: true }) : this.setState({ canOnVideo: false });
             continue;
        }
        if(key === 'unmuteMic' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canUnMuteMic: true }) : this.setState({ canUnMuteMic: false });
            continue;
        }
        if(key === 'shareScreen' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canShareScreen: true }) : this.setState({ canShareScreen: false });
            continue;
        }
        if(key === 'spotlightParticipant' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canSpotlight: true }) : this.setState({ canSpotlight: false });
            continue;
        }
        if(key === 'raiseHand' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canRaiseHands: true }) : this.setState({ canRaiseHands: false });
            continue;
        }
        if(key === 'muteOthers' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canMuteOthers: true }) : this.setState({ canMuteOthers: false });
            continue;
        }
        if(key === 'reaction' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canReact: true }) : this.setState({ canReact: false });
            continue;
        }
    }
});

公开的功能

• turnVideoOn：启用视频的功能
• unmuteMic：启用麦克风的功能
• shareScreen：共享屏幕的功能
• removeParticipant：删除参与者的功能
• hangUpForEveryOne：为每个人挂断电话的功能
• addCommunicationUser：添加通信用户的功能
• addTeamsUser：添加 Teams 用户的功能
• addPhoneNumber：添加电话号码的功能
• manageLobby：管理大厅的功能（仅限 beta 版）
• spotlightParticipant：聚焦参与者的功能（仅限 beta 版）
• removeParticipantsSpotlight：删除参与者聚焦的功能（仅限 beta 版）
• startLiveCaptions：启动实时字幕的功能（仅限 beta 版）
• stopLiveCaptions：停止实时字幕的功能（仅限 beta 版）
• raiseHand：举手的功能（仅限 beta 版）
• muteOthers：能够在会议中软静音远程参与者
• reaction：在会议中做出反应的功能（仅限 beta 版）
• viewAttendeeNames：能够在会议中查看与会者姓名

安装 SDK

找到项目级 build.gradle 文件，并将 mavenCentral() 添加到 buildscript 和 allprojects 下的存储库列表中：

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

“功能”功能是核心 Call API 的扩展功能，支持在当前通话中获取本地参与者的功能。

此功能支持注册事件侦听器，以侦听功能更改。

若要使用适用于 Windows 的“功能”通话功能，第一步是获取“功能”特性 API 对象：

获取功能特性

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.feature(Features.CAPABILITIES);

获取本地参与者的功能

Capabilities 对象具有本地参与者的功能，并且类型为 ParticipantCapability。 Capabilities 的属性包括：

• isAllowed 指示是否可以使用功能。
• reason 指示功能解决原因。

List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();

订阅 capabilitiesChanged 事件

capabilitiesCallFeature.addOnCapabilitiesChangedListener(this::OnCapabilitiesChanged);

private void OnCapabilitiesChanged(CapabilitiesChangedEvent args)
{
    String event = String.format("Capabilities Event: %s", args.getReason().toString());
    Log.i("CapabilitiesInfo", event);
    for (ParticipantCapability capability : args.getChangedCapabilities())
    {
        Log.i("CapabilitiesInfo", capability.getType().toString() + " is " capability.getReason().toString());
    }
}

公开的功能

• TurnVideoOn：启用视频的功能
• UnmuteMicrophone：将麦克风取消静音的功能
• ShareScreen：共享屏幕的功能
• RemoveParticipant：删除参与者的功能
• HangUpForEveryone：为每个人挂断电话的功能
• AddCommunicationUser：添加通信用户的功能
• AddTeamsUser：添加 Teams 用户的功能
• AddPhoneNumber：添加电话号码的功能
• ManageLobby：管理大厅的功能
• SpotlightParticipant：聚焦参与者的功能
• RemoveParticipantSpotlight：删除参与者聚焦的功能
• BlurBackground：模糊背景的功能
• CustomBackground：应用自定义背景的功能
• StartLiveCaptions：启动实时字幕的功能
• RaiseHand：举手的功能
• MuteOthers：能够在会议中软静音远程参与者

设置系统

按照以下步骤设置系统。

创建 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 包管理器安装包和依赖项

可通过 NuGet 包公开提供通话 SDK API 和库。

要查找、下载和安装通话 SDK NuGet 包，请执行以下操作：

1. 选择“工具”>“NuGet 包管理器”>“管理解决方案的 NuGet 包”，以打开 NuGet 包管理器。
2. 选择“浏览”，然后在搜索框中输入 Azure.Communication.Calling.WindowsClient。
3. 确保已选中“包括预发行版”复选框。
4. 选择 Azure.Communication.Calling.WindowsClient 包，然后选择 Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 或更新版本。
5. 在右侧窗格中选中与 Azure 通信服务项目对应的复选框。
6. 选择“安装” 。

“功能”功能是核心 Call API 的扩展功能，支持在当前通话中获取本地参与者的功能。

此功能支持注册事件侦听器，以侦听功能更改。

若要使用适用于 Windows 的“功能”通话功能，第一步是获取“功能”特性 API 对象：

获取功能特性

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.Features.Capabilities;

获取本地参与者的功能

Capabilities 对象具有本地参与者的功能，并且类型为 ParticipantCapability。 Capabilities 的属性包括：

• isAllowed 指示是否可以使用功能。
• reason 指示功能解决原因。

var capabilities = capabilitiesCallFeature.Capabilities;

订阅 capabilitiesChanged 事件

capabilitiesCallFeature.CapabilitiesChanged += Call__OnCapabilitiesChangedAsync;

private async void Call__OnCapabilitiesChangedAsync(object sender, CapabilitiesChangedEventArgs args)
{
    Trace.WriteLine(args.Reason.ToString());
    foreach (var capability in args.ChangedCapabilities)
    {
        //Prints out capability kind and resolution reason in console
        Trace.WriteLine(capability.Kind.ToString() + " is " + capability.Reason.ToString());
    }
}

公开的功能

• TurnVideoOn：启用视频的功能
• UnmuteMicrophone：将麦克风取消静音的功能
• ShareScreen：共享屏幕的功能
• RemoveParticipant：删除参与者的功能
• HangUpForEveryone：为每个人挂断电话的功能
• AddCommunicationUser：添加通信用户的功能
• AddTeamsUser：添加 Teams 用户的功能
• AddPhoneNumber：添加电话号码的功能
• ManageLobby：管理大厅的功能
• SpotlightParticipant：聚焦参与者的功能
• RemoveParticipantSpotlight：删除参与者聚焦的功能
• BlurBackground：模糊背景的功能
• CustomBackground：应用自定义背景的功能
• StartLiveCaptions：启动实时字幕的功能
• RaiseHand：举手的功能
• MuteOthers：能够在会议中软静音远程参与者

设置系统

按照以下步骤设置系统。

创建 Xcode 项目

在 Xcode 中，创建新的 iOS 项目，并选择“单视图应用”模板。 本文使用 SwiftUI 框架，因此应将“语言”设置为“Swift”，并将“界面”设置为“SwiftUI”。

在本文中，无需创建测试。 请随意清除“包括测试”复选框。

使用 CocoaPods 安装包和依赖项

1. 为应用程序创建 Podfile，如此示例所示：

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

2. 运行 pod install。

3. 使用 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")
        }
})

“功能”功能是核心 Call API 的扩展功能，支持在当前通话中获取本地参与者的功能。

此功能支持注册事件侦听器，以侦听功能更改。

若要使用适用于 Windows 的“功能”通话功能，第一步是获取“功能”特性 API 对象：

获取功能特性

let capabilitiesCallFeature =call.feature(Features.capabilities)

获取本地参与者的功能

Capabilities 对象具有本地参与者的功能，并且类型为 ParticipantCapability。 Capabilities 的属性包括：

• isAllowed 指示是否可以使用功能。
• reason 指示功能解决原因。

var capabilities = capabilitiesCallFeature.capabilities

订阅 capabilitiesChanged 事件

capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()

public class CapabilitiesCallDelegate : CapabilitiesCallFeatureDelegate
{
    public func capabilitiesCallFeature(_ capabilitiesCallFeature: CapabilitiesCallFeature, didChangeCapabilities args: CapabilitiesChangedEventArgs) {
        let changedReason = args.reason
        let changedCapabilities = args.changedCapabilities
    }
}

公开的功能

• TurnVideoOn：启用视频的功能
• UnmuteMicrophone：将麦克风取消静音的功能
• ShareScreen：共享屏幕的功能
• RemoveParticipant：删除参与者的功能
• HangUpForEveryone：为每个人挂断电话的功能
• AddCommunicationUser：添加通信用户的功能
• AddTeamsUser：添加 Teams 用户的功能
• AddPhoneNumber：添加电话号码的功能
• ManageLobby：管理大厅的功能
• SpotlightParticipant：聚焦参与者的功能
• RemoveParticipantSpotlight：删除参与者聚焦的功能
• BlurBackground：模糊背景的功能
• CustomBackground：应用自定义背景的功能
• StartLiveCaptions：启动实时字幕的功能
• RaiseHand：举手的功能
• MuteOthers：能够在会议中软静音远程参与者

支持的通话类型

此功能目前仅支持 Azure 通信服务会议室通话类型和团队会议通话类型

原因

下表提供了有关操作不可用的原因的更多信息，并提供了有关如何使该操作可用的建议。

Reason	说明	解决方法
Capable	允许执行操作。
CapabilityNotApplicableForTheCallType	通话类型会阻止此操作。	如果需要进行此操作，请考虑其他类型的通话。 通话类型包括：一对一通话、群组通话、一对一 Teams 互操作通话、一对一 Teams 互操作群组通话、会议室和会议。
ClientRestricted	运行时环境正在阻止此操作	通过更改操作系统、浏览器、平台或硬件来取消阻止设备上的操作。 可以在我们的文档中找到受支持的环境。
UserPolicyRestricted	Microsoft 365 用户的策略会阻止此操作。	使用 ACS SDK 更改分配给会议组织者、通话发起者或 Microsoft 365 用户的策略，从而启用此操作。 目标用户取决于操作的类型。 在 Teams 中了解有关 Teams 策略的详细信息。 Teams 管理员可以更改这些策略。
RoleRestricted	分配的角色会阻止此操作。	将用户提升为不同的角色，使此操作可用。
FeatureNotSupported	此通话类型不支持这些功能。	如果希望此功能可用于此通话类型，请在 Azure 反馈频道中告诉我们。
MeetingRestricted	Teams 会议选项会阻止此操作。	Teams 会议组织者或共同组织者需要更改会议选项才能启用此操作。
NotInitialized	此功能尚未初始化。	在 this.call.feature(Features.Capabilities) 上订阅 capabilitiesChanged 事件，了解何时初始化功能。
NotCapable	用户类型会阻止此操作。	此操作仅允许特定类型的标识。 使用 Microsoft 365 标识启用此操作。
TeamsPremiumLicenseRestricted	Microsoft 365 用户需要分配 Teams Premium 许可证。	通过使用 SDK 将 Teams 高级版许可证分配给 Teams 会议组织者或 Microsoft 365 用户来启用此操作。 目标用户取决于操作的类型。 Microsoft 365 管理员可以分配所需的许可证。
ExplicitConsentRequired	需要获得同意才能允许该操作。	通过调用 this.call.feature(Features.Recording) 或 this.call.feature(Features.Transcription) 下的方法 grantTeamsConsent() 来同意录制或听录。

后续步骤

• 了解如何管理视频
• 了解如何管理通话
• 了解如何记录通话