你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
通话 SDK 概述
通过 Azure 通信服务，最终用户浏览器、应用和服务可驱动语音和视频通信。 本页重点介绍呼叫客户端 SDK，它可嵌入到网站和本机应用程序中。 本页提供呼叫客户端功能的详细说明，例如平台和浏览器支持信息。 服务使用呼叫自动化 API 以编程方式管理和访问呼叫。 会议室 API 是可选的 Azure 通信服务 API，可将其他功能（例如角色和权限）添加到语音或视频通话。
若要使用呼叫 SDK 构建自己的用户体验，请查看呼叫快速入门或呼叫主图示例。
如果想要获得最终用户体验方面的帮助，Azure 通信服务 UI 库提供了一系列生产就绪的开源 UI 组件，以供添加到应用程序中。 借助这组预生成控件，可以使用 Microsoft 的 Fluent 设计语言创建美观的通信体验。 若要了解有关 UI 库的详细信息，请访问概述网站。
开始开发后，请查看已知问题页，找到我们正在处理的 bug。
SDK 链接
| 平台 | Web (JavaScript) | Windows (.NET) | iOS | Android | 其他 |
|---|---|---|---|---|---|
| 调用 | npm | NuGet | GitHub | Maven | |
| UI 库 | npm | - | GitHub | GitHub | GitHub、Storybook |
主要功能
- 设备管理和媒体 - 呼叫 SDK 提供所需的工具用于绑定到音频和视频设备、对内容进行编码以通过通信数据平面高效传输，并在指定的输出设备和视图中呈现内容。 此外，还提供 API 用于屏幕和应用程序共享。
- PSTN - 呼叫 SDK 可以使用你在 Azure 门户中获取的电话号码或者以编程方式，通过传统的公共交换电话网络发起语音呼叫。 还可使用会话边界控制器提供自己的号码。
- Teams 会议和呼叫 - 呼叫 SDK 可加入 Teams 会议，并与 Teams 语音和视频数据平面交互。
- 加密 - 呼叫 SDK 将加密流量并防止在线篡改。
- 寻址 - Azure 通信服务提供通用标识用于对通信终结点进行寻址。 客户端使用这些标识对服务进行身份验证并相互通信。 这些标识用于呼叫 API，使客户端了解到已连接到（花名册中的）何人。
- 代码访问安全性
- “名册”控件、“计划”控件和用户角色/权限通过 Virtual Rooms 强制执行。
- 用户发起新通话或加入现有通话的能力可通过用户标识和令牌进行管理
- 通知 - 呼叫 SDK 提供可以在接到来电时通知客户端的 API。 如果你的应用不是在前台运行，可以使用触发弹出式通知（“toast”）的模式来通知最终用户接到了来电。
- 媒体统计信息 - 呼叫 SDK 提供对 VoIP 和视频通话的指标的综合见解。 有了此信息，开发人员可以更清楚地了解通话质量，并做出明智的决策，进一步增强他们的通信体验。
- 视频约束 - 呼叫 SDK 提供了 API，使你能够通过调整分辨率和帧速率等参数，在视频通话期间调节视频质量和其他参数，从而支持不同视频质量水平的不同通话情况
- 面向用户的诊断 (UFD) - 通信 SDK 提供了事件，它们旨在让你深入了解可能影响通话质量的基础问题。 开发人员可以订阅网络信号弱或麦克风静音等触发器，确保他们始终知晓影响通话的任何因素。
详细功能
下面列出了 Azure 通信服务通话 SDK 中当前提供的功能集。
| 功能组 | 功能 | JS | Windows | Java (Android) | Objective-C (iOS) |
|---|---|---|---|---|---|
| 核心功能 | 在两个用户之间启动一对一呼叫 | ✔️ | ✔️ | ✔️ | ✔️ |
| 为两个以上的用户（最多 100 个用户）启动组呼叫 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 将两个用户的一对一呼叫升级为两个以上用户的组呼叫 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 在一个组呼叫开始后加入它 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 邀请其他 VoIP 参与者加入正在进行的组呼叫 | ✔️ | ✔️ | ✔️ | ✔️ | |
| Mid 呼叫控制 | 打开/关闭视频 | ✔️ | ✔️ | ✔️ | ✔️ |
| 将麦克风静音/取消静音 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 将其他参与者设为静音 | ✔️ | ✔️1 | ✔️1 | ✔️1 | |
| 切换照相机 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 本地保持/取消保持 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 有源扬声器 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 选择通话扬声器 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 选择呼叫麦克风 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 显示参与者的状态 空闲、早期媒体、正在连接、已连接、等候接听、接听中、已断开连接 |
✔️ | ✔️ | ✔️ | ✔️ | |
| 显示呼叫的状态 早期媒体、正在传入、正在连接、正在响铃、已连接、通话保持、正在断开连接、已断开连接 |
✔️ | ✔️ | ✔️ | ✔️ | |
| 显示参与者是否静音 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 显示参与者退出通话的原因 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 屏幕共享 | 在应用程序中共享整个屏幕 | ✔️ | ✔️2 | ✔️2 | ✔️2 |
| 共享特定的应用程序（从正在运行的应用程序列表中） | ✔️ | ✔️2 | ❌ | ❌ | |
| 从打开的选项卡列表中共享 web 浏览器选项卡 | ✔️ | ||||
| 在屏幕共享过程中共享系统音频 | ✔️ | ❌ | ❌ | ❌ | |
| 参与者可以查看远程屏幕共享 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 名单 | 列出参与者 | ✔️ | ✔️ | ✔️ | ✔️ |
| 删除参与者 | ✔️ | ✔️ | ✔️ | ✔️ | |
| PSTN | 启动与 PSTN 参与者的一对一呼叫 | ✔️ | ✔️ | ✔️ | ✔️ |
| 与 PSTN 参与者进行组呼叫 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 将 PSTN 参与者的一对一呼叫升级为组呼叫 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 以 PSTN 参与者身份在组呼叫中拨出 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 对早期媒体的支持 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 常规 | 使用音频测试服务测试麦克风、扬声器和照相机（可通过呼叫 8:echo123 使用） | ✔️ | ✔️ | ✔️ | ✔️ |
| 设备管理 | 请求使用音频和/或视频的权限 | ✔️ | ✔️ | ✔️ | ✔️ |
| 获取相机列表 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 设置相机 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 获取所选相机 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 获取麦克风列表 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 设置麦克风 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 获取所选麦克风 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 获取扬声器列表 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 设置扬声器 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 获取所选扬声器 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 视频渲染 | 在多个位置（本地相机或远程流）渲染单个视频 | ✔️ | ✔️ | ✔️ | ✔️ |
| 设置/更新缩放模式 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 渲染远程视频流 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 视频效果 | 背景模糊 | ✔️ | ✔️ | ✔️ | ✔️ |
| 自定义背景图像 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 音效 | 音乐模式 | ❌ | ✔️ | ✔️ | ✔️ |
| 回声消除 | ❌ | ✔️ | ✔️ | ✔️ | |
| 噪声抑制 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 自动增益控制 (AGC) | ❌ | ✔️ | ✔️ | ✔️ | |
| 通知 4 | 推送通知 | ✔️ | ✔️ | ✔️ | ✔️ |
| 自定义上下文 | 在通话中添加用户到用户 (UUI) 或自定义标头 | ✔️ | ❌ | ❌ | ❌ |
1“将其他人静音”功能目前为公共预览版。
2 可使用原始媒体 API 实现共享屏幕功能。 若要了解详细信息，请访问原始媒体访问快速入门指南。
3 呼叫 SDK 没有针对这些函数的显式 API，你应转而所用 Android 和 iOS OS API 来实现。
4 本机平台中 TTL 的最大值为 180 天（15,552,000 秒），最小值为 5 分钟（300 秒）。 对于 CTE（自定义 Teams 终结点）/M365 标识，最大 TTL 值为 24 小时（86,400 秒）。
OS 和浏览器提供的 JavaScript 呼叫 SDK 支持
下表显示了当前可用的一组受支持的浏览器。 除非另有说明，我们支持浏览器最新的三个主版本（对于 Safari，则支持最新的三个次要版本）。
| 平台 | Chrome | Safari | Edge | Firefox | WebView | Electron |
|---|---|---|---|---|---|---|
| Android | ✔️ | ❌ | ✔️ | ❌ | ✔️ | ❌ |
| iOS | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ |
| macOS | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ |
| Windows | ✔️ | ❌ | ✔️ | ✔️ | ❌ | ✔️ |
| Ubuntu/Linux | ✔️ | ❌ | ❌ | ❌ | ❌ | ❌ |
- iOS 或 Android 移动浏览器不支持传出屏幕共享。
- Firefox 支持以公共预览版提供。
- 目前，呼叫 SDK 仅支持 Android 上的 Android System WebView 和公共预览版的 iOS WebView(WKWebView)。 其他 OS 平台上的其他类型的嵌入式浏览器或 WebView 不受官方支持，例如 GeckoView、Chromium Embedded Framework (CEF) 和 Microsoft Edge WebView2。 在这些平台上运行 JavaScript 呼叫 SDK 的操作没有经过积极的测试，它可能可行，也可能不可行。
- Safari 上的 iOS 应用无法枚举/选择麦克风和扬声器设备（例如蓝牙）。 只有 iOS 出现此问题，操作系统控制着默认设备选择。
调用客户端 - 浏览器安全模型
通过 HTTPS 使用 WebRTC
WebRTC API（如 getUserMedia）要求通过 HTTPS 处理调用这些 API 的应用。 对于本地开发，可使用 http://localhost。
在 iframe 中嵌入通信服务调用 SDK
各种浏览器中都提供了一个新的权限策略（也称为功能策略）。 此策略通过控制应用程序如何通过跨源 iframe 元素访问设备的摄像头和麦克风来影响调用方案。
如果要使用 iframe 从其他域托管应用的一部分，则必须将具有正确值的 allow 属性添加到 iframe。
例如，此 iframe 允许摄像头和麦克风访问：
<iframe allow="camera *; microphone *">
Android 调用 SDK 支持
- 支持 Android API 级别 21 或更高版本
- 支持 Java 7 或更高版本
- 支持 Android Studio 2.0
我们强烈建议通过访问受支持的 Android 平台来识别和验证你的方案
iOS 调用 SDK 支持
- 在编译时支持 iOS 10.0+，运行时支持 iOS 12.0+
- Xcode 12.0+
- 支持 iPadOS 13.0+
最长通话持续时间
最长通话持续时间为 30 小时，达到最长通话持续时间的参与者将断开通话连接。
受支持的传入视频流数
Azure 通信服务呼叫 SDK 支持以下流式传输配置：
| 限制 | Web | Windows/Android/iOS |
|---|---|---|
| 最多 # 个可同时发送的传出本地数据流 | 1 个视频和 1 个屏幕共享 | 1 个视频 + 1 个屏幕共享 |
| 最多 # 个可同时呈现的传入远程数据流 | 桌面浏览器上的 16 个视频 + 1 个屏幕共享*、Web 移动浏览器上的 4 个视频 + 1 个屏幕共享 | 9 个视频 + 1 个屏幕共享 |
* 从 Azure 通信服务 Web 呼叫 SDK 版本 1.16.3 开始，尽管呼叫 SDK 不强制实施这些限制，但如果超出这些限制，用户可能会遇到性能下降的情况。 使用最佳视频计数的 API 来确定 Web 环境可支持的当前传入视频流数。 为了正确支持 16 个传入视频，计算机应至少有 16GB RAM 以及一个至少 4 核且使用时间不超过 3 年的 CPU
支持的视频分辨率
Azure 通信服务通话 SDK 会在通话期间自动调整视频和屏幕共享流的分辨率。
注意
分辨率可能因通话参与者数、客户端可用的带宽量、呈现远程视频结构和其他整体呼叫参数的本地参与者的硬件功能而异。
Azure 通信服务通话 SDK 支持发送以下视频分辨率
| 最大视频分辨率 | WebJS | iOS | Android | Windows |
|---|---|---|---|---|
| 发送视频 | 720P | 720P | 720P | 1080P |
| 发送屏幕共享 | 1080P | 1080P | 1080P | 1080P |
| 接收远程视频流或屏幕共享 | 1080P | 1080P | 1080P | 1080P |
通话支持中的参与者数
- 最多有 350 名用户可以加入组呼叫、会议室或 Teams + ACS 呼叫。
- 通话规模达到 100 名以上参与者后，只有前 4 名打开了相机的占主导地位讲话人可以被看到。
- 通过人数超过 100 名时，可查看的传入视频呈现数从 4x4（16 个传入视频）自动下降到 2x2（4 个传入视频）。
- 当用户数低于 100 人时，可支持的传入视频数将回到 4x4（16 个传入视频）。
呼叫 SDK 超时
以下超时适用于通信服务呼叫 SDK：
| 操作 | 超时(以秒为单位) |
|---|---|
| 重新连接/删除参与者 | 60 |
| 在调用中添加或删除新的模态（启动/停止视频或屏幕共享） | 40 |
| 呼叫转移操作超时 | 60 |
| 1:1 呼叫建立超时 | 85 |
| 组呼叫建立超时 | 85 |
| PSTN 呼叫建立超时 | 115 |
| 将 1:1 呼叫升级到组呼叫超时 | 115 |
后续步骤
有关详细信息，请参阅以下文章：
- 熟悉常规呼叫流
- 了解呼叫类型
- 了解呼叫自动化 API，通过它可生成基于服务器的呼叫工作流，这些工作流通过客户端应用程序路由和控制呼叫。
- 规划 PSTN 解决方案