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

通话前诊断概述

项目
11/14/2024

重要

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

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

开发人员可以使用呼叫前 API 功能以编程方式验证客户端是否已准备好参与 Azure 通信服务呼叫。只能使用呼叫 SDK 访问呼叫前功能。呼叫前 API 提供多种诊断，包括设备、连接和呼叫质量诊断。通话前诊断功能仅适用于 Web (JavaScript)。我们计划将来在不同平台上提供这些功能。向我们提供反馈，告知我们希望在哪些平台上使用呼叫前诊断功能。

先决条件

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

访问呼叫前诊断

重要

从呼叫 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，最简单的解决方法是让用户改用支持的浏览器。请参阅呼叫 SDK 概述 > OS 和浏览器支持的 JavaScript 呼叫 SDK中支持的浏览器。

注意

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

设备访问

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


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

如果测试失败且音频和视频的权限为 false，则用户不应继续参与呼叫。应提示用户启用权限。完成此操作的最佳方式是提供有关如何基于用户使用的操作系统、版本和浏览器获取相应权限的具体说明。有关权限的详细信息，请参阅 Web 浏览器中高级呼叫体验的清单。

设备枚举

设备可用性。检查是否可在系统中检测到麦克风、摄像头和扬声器设备并且这些设备可供使用。返回或 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，则提示用户尝试使用不同网络或验证其当前网络的带宽可用性。确保未发生其他高带宽活动。

定价

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

通过