通話前診断の概要

通話前 API 機能を使用すると、開発者は、Azure Communication Services 通話に参加するためのクライアントの準備状況をプログラムで検証できます。 通話前機能には、Calling SDK を使用してのみアクセスできます。 通話前診断機能では、デバイス、接続、通話の品質など、複数の診断が提供されます。 通話前診断機能は、Web (JavaScript) でのみ使用できます。 今後、プラットフォーム間でこれらの機能を有効にする予定です。 通話前診断がどのプラットフォームに欲しいか、フィードバックをお寄せください。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。

• Node.js のアクティブな長期サポート (LTS) バージョンをお勧めします。

• アクティブな Communication Services リソース。 Communication Services リソースを作成します。

• 通話クライアントをインスタンス化するためのユーザー アクセス トークン。 ユーザー アクセス トークンを作成して管理する方法を参照してください。 Azure CLI を使用し、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。 必ず Azure portal を介してリソースから接続文字列をコピーしてください。

  az communication identity token issue --scope voip --connection-string "yourConnectionString"
  

  詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

通話前診断へのアクセス

通話前診断にアクセスするには、callClient を初期化して Azure Communication Services アクセス トークンをプロビジョニングする必要があります。 そこでは、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 の概要」 > 「OS とブラウザーによる JavaScript Calling SDK のサポート」で、サポートされているブラウザーを確認してください。

デバイス アクセス

アクセス許可チェックにより、ビデオ デバイスとオーディオ デバイスがアクセス許可の観点から利用できるかどうかを確認します。 audio と video のデバイスに boolean 値を提供します。

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

テストが失敗し、オーディオとビデオのアクセス許可が false の場合、ユーザーは通話への参加を継続しないでください。 代わりに、アクセス許可を有効にするようユーザーに求めます。 これを行うには、使用している OS、バージョン、ブラウザーに基づいて、アクセス許可へのアクセス方法に関する具体的な指示を提供することをお勧めします。 アクセス許可の詳細については、Web ブラウザーで高度な通話エクスペリエンスを提供するためのチェックリストに関するページを参照してください。

デバイスの列挙

デバイスの可用性。 マイク、カメラ、スピーカーのデバイスがシステムで検出され、使用できる状態になっているかどうかを確認します。 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、プロキシ、ファイアウォールなどのネットワーク条件に起因する場合もあります。 推奨されるネットワーク設定の詳細については、「ネットワークの推奨事項」を参照 してください。
• 帯域幅が Bad である場合は、別のネットワークを試すか、現在のネットワークで帯域幅の可用性を確認するようにユーザーに求めます。 他の高帯域幅アクティビティが発生しないようにします。

価格

通話前診断テストが実行されると、バックグラウンドで通話時間 (分) を使用して診断が実行されます。 テストは約 30 秒間続き、30 秒間の通話が使用され、参加者 1 人あたり 1 分 0.004 ドルの標準料金で課金されます。 通話前診断の場合、料金は参加者 1 人 x 30 秒 = $0.002 です。

次のステップ

• 診断ツールを使用してネットワークの状態を確認する
• ユーザー向けの診断 API を確認する
• アプリケーションでメディア品質統計を有効にする
• Azure Monitor で呼び出しログを使用する