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

呼叫前诊断

项目
10/26/2023

重要

Azure 通信服务的这一功能目前以预览版提供。

预览版 API 和 SDK 在没有服务级别协议的情况下提供。建议不要将它们用于生产工作负荷。某些功能可能不受支持或者已受限。

开发人员可以使用呼叫前 API 以编程方式验证客户端是否已准备好参与 Azure 通信服务呼叫。可以通过呼叫 SDK 访问呼叫前 API。这些 API 提供多种诊断，包括设备、连接和呼叫质量。呼叫前 API 仅适用于 Web (JavaScript)。我们将在未来跨平台启用这些功能，向我们提供有关想要在其中查看预调用 API 的平台的反馈。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
推荐 Node.js 活动的长期支持 (LTS) 版本。
活动的通信服务资源。创建通信服务资源。
用于实例化呼叫客户端的用户访问令牌。了解如何创建和管理用户访问令牌。还可以使用 Azure CLI，通过连接字符串运行下一个命令来创建用户和访问令牌。（需要通过 Azure 门户从资源中获取连接字符串。）
```
az communication identity token issue --scope voip --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

访问呼叫前 API

重要

从通话 SDK 的 1.9.1-beta.1 版本开始，即可使用预呼叫诊断。请确保在尝试下一说明时使用该版本。

若要访问预调用 API，需要初始化callClient并预配Azure 通信服务访问令牌。然后可以通过该令牌访问 PreCallDiagnostics 功能和 startTest 方法。

import { CallClient, Features} from "@azure/communication-calling";
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

const callClient = new CallClient(); 
const tokenCredential = new AzureCommunicationTokenCredential("INSERT ACCESS TOKEN");
const preCallDiagnosticsResult = await callClient.feature(Features.PreCallDiagnostics).startTest(tokenCredential);

运行完成后，开发人员可以访问结果对象。

诊断结果

呼叫前 API 返回设备的完整诊断信息，包括设备权限、可用性和兼容性、呼叫质量统计信息和呼叫中诊断等详细信息。结果作为 PreCallDiagnosticsResult 对象返回。


export declare type PreCallDiagnosticsResult  = {
    deviceAccess: Promise<DeviceAccess>;
    deviceEnumeration: Promise<DeviceEnumeration>;
    inCallDiagnostics: Promise<InCallDiagnostics>;
    browserSupport?: Promise<DeviceCompatibility>;
    id: string;
    callMediaStatistics?: Promise<MediaStatsCallFeature>;
};

可以使用常量访问 preCallDiagnosticsResult 单个结果对象。单个测试的结果会返回，因为它们已完成，许多测试结果立即可用。如果使用 inCallDiagnostics 测试，结果最多可能需要 1 分钟，因为测试会验证视频和音频的质量。

浏览器支持

浏览器兼容性检查。检查 Browser 和 OS 兼容性并返回 Supported 或 NotSupported 值。


const browserSupport =  await preCallDiagnosticsResult.browserSupport;
  if(browserSupport) {
    console.log(browserSupport.browser)
    console.log(browserSupport.os)
  }

如果测试失败并且用户使用的浏览器是 NotSupported，最简单的修复方法是让用户改用支持的浏览器。请在我们的文档中了解支持的浏览器。

注意

已知问题：browser support 测试不返回正确的值，而是返回 Unknown。

设备访问

权限检查。从权限的角度检查视频和音频设备是否可用。为 audio 和 video 设备提供 boolean 值。


  const deviceAccess =  await preCallDiagnosticsResult.deviceAccess;
  if(deviceAccess) {
    console.log(deviceAccess.audio)
    console.log(deviceAccess.video)
  }

如果测试失败并且音频和视频的权限为 false，则用户不应继续参与呼叫。而需要提示用户启用权限。为此，提供了有关如何基于操作系统、版本和浏览器访问权限的特定说明。有关权限的详细信息，检查建议。

设备枚举

设备可用性。检查是否可在系统中检测到麦克风、摄像头和扬声器设备并且这些设备可供使用。返回 Available 或 NotAvailable 值。


  const deviceEnumeration = await preCallDiagnosticsResult.deviceEnumeration;
  if(deviceEnumeration) {
    console.log(deviceEnumeration.microphone)
    console.log(deviceEnumeration.camera)
    console.log(deviceEnumeration.speaker)
  }

如果设备不可用，用户不应继续加入呼叫。应提示用户检查设备连接，以确保正确连接了任何耳机、摄像头或扬声器。有关设备管理的详细信息，检查我们的文档

呼入诊断

执行快速呼叫以检查音频和视频的呼入指标并返回结果。包括连接（connected，布尔值）、带宽质量（bandWidth、'Bad' | 'Average' | 'Good'）以及音频和视频的呼叫诊断结果 (diagnostics)。将提供 jitter、packetLoss 和 rtt 诊断结果，并使用简单质量等级 ('Bad' | 'Average' | 'Good') 生成结果。

InCall 诊断使用媒体质量统计信息来计算质量分数和诊断问题。在呼叫前诊断过程中，可以使用完整的媒体质量统计信息。这些统计信息包括视频和音频指标中的原始值，这些指标可以以编程方式使用。 InCall 诊断在媒体质量统计信息的基础上提供了一个方便层，无需处理所有原始数据即可使用结果。有关访问说明，请参阅媒体统计信息部分。


  const inCallDiagnostics =  await preCallDiagnosticsResult.inCallDiagnostics;
  if(inCallDiagnostics) {    
    console.log(inCallDiagnostics.connected)
    console.log(inCallDiagnostics.bandWidth)
    console.log(inCallDiagnostics.diagnostics.audio)
    console.log(inCallDiagnostics.diagnostics.video)
  }

在此步骤中，需要注意多个故障点。 API 提供的值基于服务所需的阈值。这些原始阈值可以在我们的媒体质量统计信息文档中找到。

如果连接失败，应提示用户重新检查其网络连接。连接失败也可归因于 DNS、代理或防火墙等网络状况。有关建议的网络设置的详细信息，检查我们的文档。
如果带宽为 Bad，则应提示用户尝试使用不同的网络，或验证其当前网络的带宽可用性。确保未发生其他高带宽活动。

媒体统计信息

使用 preCallDiagnosticsResult 功能随附的 callMediaStatistics 可以获取抖动、丢包、rtt 等质量指标的细致统计信息。请参阅链接文章中的可用指标的完整列表和说明。你可以订阅呼叫媒体统计信息以获取这些指标的完整集合。此统计信息是用于计算 InCall 诊断结果的原始指标，可以精细地用于进一步分析。


const mediaStatsCollector = callMediaStatistics.startCollector(); 

mediaStatsCollector.on('mediaStatsEmitted', (mediaStats: SDK.MediaStats) => { 
    // process the stats for the call. 
    console.log(mediaStats);
});

定价

当呼叫前诊断测试运行时，它会在幕后使用呼叫分钟数来运行诊断。该测试持续大约 30 秒，最多 30 秒的呼叫将按每位参与者每分钟 0.004 美元的标准费率收费。对于呼叫前诊断，费用将为 1 位参与者 x 30 秒 = 0.002 美元。

Share via