通話前診斷

文章
04/26/2024

重要

此 Azure 通訊服務功能目前處於預覽狀態。

提供的預覽 API 和 SDK 並無服務等級協定。建議您不要將其用於生產工作負載。有些功能可能不受支援，或是在功能上有所限制。

通話前 API 可讓開發人員以程式設計的方式，驗證用戶端對於加入 Azure 通訊服務通話的整備程度。您可以透過通話 SDK 存取通話前 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)
  }

如果測試失敗且音訊和視訊沒有權限，使用者不應該繼續加入通話。相反地，您必須提示使用者去啟用權限。若要這樣做，最佳方式是提供具體的指示，告知他們如何根據所使用的作業系統、版本和瀏覽器取得存取權限。如需權限的詳細資訊，請參閱我們的建議事項。

裝置列舉

裝置可用性。檢查系統是否有偵測到麥克風、相機和喇叭裝置，且這些裝置已可使用。回報 Available 或 NotAvailable 值。


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

如果裝置無法使用，使用者就不應該繼續加入通話。相反地，應該提示使用者檢查裝置連線，以確認任何頭戴式裝置、相機或喇叭都已正確連線。如需裝置管理的詳細資訊，請參閱我們的文件

InCall 診斷

執行快速通話來檢查音訊和視訊的通話計量並回報結果。包括連線能力 (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、Proxy 或防火牆。如需建議網路設定的詳細資訊，請參閱我們的文件。
如果頻寬為 Bad，則應提示使用者嘗試使用不同的網路，或確認其目前網路頻寬的可用性。請確定目前沒有進行任何其他高頻寬活動。

媒體統計資料

如需品質計量的精細統計資料，例如抖動、封包遺失、rtt 等，我們提供 callMediaStatistics 作為 preCallDiagnosticsResult 功能的一部分。請參閱連結文章的可用計量的完整清單和說明。您可以訂閱通話媒體統計資料以取得其完整資訊。此統計資料是用來計算 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。

分享方式：