預先呼叫診斷

發行項
11/13/2024

重要

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

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

預先呼叫 API 功能可讓開發人員以程式設計方式驗證用戶端加入 Azure 通訊服務呼叫的整備程度。您只能使用通話 SDK 存取預先呼叫功能。預先呼叫診斷功能提供多個診斷，包括裝置、連線和通話品質。預先呼叫診斷功能僅適用於 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 版開始，即可使用預先呼叫診斷。遵循這些指示時，請務必使用該版本或更新版本。

若要存取預先呼叫診斷，您必須初始化 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);

執行完畢後，開發人員就可以存取結果物件。

診斷結果

預先呼叫診斷會傳回裝置的完整診斷，包括裝置許可權、可用性和相容性、通話品質統計數據和通話內診斷等詳細數據。結果會以 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概觀 > JavaScript 呼叫 SDK 支援的作業系統和瀏覽器中的瀏覽器。

注意

已知問題：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)
  }

如果裝置無法使用，使用者不應該繼續加入通話。相反地，提示使用者檢查裝置連線，以確保任何耳機、相機或喇叭都已正確連接。如需裝置管理的詳細資訊，請參閱在通話期間管理影片。

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，請提示用戶嘗試不同的網路，或確認其目前網路上的頻寬可用性。請確定沒有其他高頻寬活動進行。

定價

當預先呼叫診斷測試在幕後執行時，它會使用呼叫分鐘來執行診斷。測試持續約 30 秒，最多使用 30 秒的通話時間，每個參與者每分鐘的標準費率為 $0.004。針對預先呼叫診斷的情況，費用為1個參與者 x 30 秒 = $0.002。

共用方式為