Share via

事前呼び出し診断

  • [アーティクル]

重要

Azure Communication Services のこの機能は、現在プレビュー段階にあります。

プレビューの API と SDK は、サービス レベル アグリーメントなしに提供されます。 運用環境のワークロードには使用しないことをお勧めします。 一部の機能はサポート対象ではなく、機能が制限されることがあります。

詳細については、「Microsoft Azure プレビューの追加利用規約」を確認してください。

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

前提条件

事前呼び出し API へのアクセス

重要

通話前診断は、Calling SDK のバージョン 1.9.1-beta.1 以降で使用できます。 次の手順を試すときは、必ずそのバージョンを使用してください。

事前呼び出し API にアクセスするには、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);

実行が完了すると、結果オブジェクトにアクセスできます。

診断結果

事前呼び出し 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 である場合、サポートされているブラウザーに切り替えるようユーザーに求めると、もっとも簡単に修正できます。 サポートされているブラウザーについては、 ドキュメントを参照してください。

Note

既知の問題: 正しい値を返す必要がある場合にbrowser support 返されるテストUnknown。

デバイス アクセス

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


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

テストが失敗し、オーディオとビデオのアクセス許可が false の場合、ユーザーは通話への参加を継続しないでください。 代わりに、ユーザーにアクセス許可を有効にするようプロンプトを表示する必要があります。 これを行うには、使用する OS、バージョン、ブラウザーに基づいてアクセス許可へのアクセス方法に関する具体的な指示を提供することをお勧めします。 アクセス許可の詳細については、 推奨事項をご覧ください。

デバイスの列挙

デバイスの可用性。 マイク、カメラ、スピーカーのデバイスがシステムで検出され、使用できる状態になっているかどうかを確認します。 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) の通話診断が含まれます。 診断が提供され、単純な品質グレード ('Bad' | 'Average' | 'Good') を使用して、jitter、packetLoss、rtt と結果が生成されます。

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 である場合は、別のネットワークを試すか、現在のネットワークで帯域幅の可用性を確認するように求めるプロンプトが表示されます。 他の高帯域幅アクティビティが発生しないようにします。

メディア統計

ジッター、パケット損失、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 秒間の通話が使用され、参加者 1 人あたり 1 分 0.004 ドルの標準料金で課金されます。 通話前診断の場合、料金は参加者 1 人 x 30 秒 = $0.002 になります。

次のステップ