Azure Communication Services でのトラブルシューティング

このドキュメントでは、Communication Services ソリューションで発生する可能性がある問題のトラブルシューティングについて説明します。 SMS のトラブルシューティングを行う場合は、Event Grid で配信レポートを有効にすることで、SMS の配信の詳細を取得できます。

ヘルプの​​表示

開発者の皆さんは、ご質問の送信、機能のご提案、および問題のレポートに関してぜひご協力ください。 詳細については、専用のサポートとヘルプ オプションのページを参照してください。

特定の問題のトラブルシューティングに役立てるため、次の情報が 1 つ以上必要な場合があります。

• MS-CV ID: 通話とメッセージのトラブルシューティングを行います。
• 通話 ID: Communication Services の通話を識別します。
• SMS メッセージ ID: SMS メッセージを識別します。
• ショート コード プログラムの簡易 ID: ショート コード プログラムの簡単なアプリケーションを識別します。
• 無料電話番号検証キャンペーン要約 ID: 無料電話番号検証キャンペーンの簡易アプリケーションを識別するために使用されます。
• メール ID: メール送信要求を識別します。
• 関連付け ID: Call Automation を使って行われた要求の識別に使われます。
• 通話ログ: 呼び出しとネットワークの問題のトラブルシューティングに使用できる詳細情報が含まれています。

調整と制限の詳細については、サービスの制限に関するページを参照してください。

MS-CV ID にアクセスする

SDK を初期化する際に、clientOptions オブジェクト インスタンスで診断を構成すると MS-CV ID にアクセスできます。 チャット、ID、VoIP 呼び出しなど、任意の Azure SDK の診断を構成できます。

クライアント オプションの例

次のコード スニペットは、診断の構成を示しています。 SDK の診断を有効にすると、構成済みのイベント リスナーに診断の詳細を出力できます。

// 1. Import Azure.Core.Diagnostics
using Azure.Core.Diagnostics;

// 2. Initialize an event source listener instance
using var listener = AzureEventSourceListener.CreateConsoleLogger();
Uri endpoint = new Uri("https://<RESOURCE-NAME>.communication.azure.net");
var (token, communicationUser) = await GetCommunicationUserAndToken();
CommunicationUserCredential communicationUserCredential = new CommunicationUserCredential(token);

// 3. Setup diagnostic settings
var clientOptions = new ChatClientOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "*" },
        LoggedQueryParameters = { "*" },
        IsLoggingContentEnabled = true,
    }
};

// 4. Initialize the ChatClient instance with the clientOptions
ChatClient chatClient = new ChatClient(endpoint, communicationUserCredential, clientOptions);
ChatThreadClient chatThreadClient = await chatClient.CreateChatThreadAsync("Thread Topic", new[] { new ChatThreadMember(communicationUser) });

from azure.communication.chat import ChatClient, CommunicationUserCredential
endpoint = "https://communication-services-sdk-live-tests-for-python.communication.azure.com"
chat_client = ChatClient(
    endpoint,
    CommunicationUserCredential(token),
    http_logging_policy=your_logging_policy)

Call Automation に必要なアクセス ID

通話管理や記録の問題など、Call Automation SDK に関する問題をトラブルシューティングする場合は、失敗した通話または操作を特定するのに役立つ ID を収集する必要があります。 次の 2 つの ID のいずれかを指定できます。

• API 応答のヘッダーから、X-Ms-Skype-Chain-Id フィールドを見つけます。

  

• アクションの実行後にアプリケーションが受け取るコールバック イベントから。 たとえば、CallConnected や PlayFailed では correlationID を見つけます。

  

これらの ID のいずれかに加えて、失敗したユース ケースと、失敗が発生したときのタイムスタンプに関する詳細を指定する必要があります。

クライアント通話 ID にアクセスする

音声通話またはビデオ通話のトラブルシューティングを行う際に、call ID の提供が必要になることがあります。 call オブジェクトの id プロパティを使用して、この値にアクセスします。

// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)

// The `call id` property can be retrieved by calling the `call.getCallId()` method on a call object after a call ends
// todo: the code snippet suggests it's a property while the comment suggests it's a method call
print(call.callId)

// The `call id` property can be retrieved by calling the `call.getCallId()` method on a call object after a call ends
// `call` is an instance of a call created by `callAgent.startCall(…)` or `callAgent.join(…)` methods
Log.d(call.getCallId())

SMS メッセージ ID にアクセスする

SMS の問題については、応答オブジェクトからメッセージ ID を収集できます。

// Instantiate the SMS client
const smsClient = new SmsClient(connectionString);
async function main() {
  const result = await smsClient.send({
    from: "+18445792722",
    to: ["+1972xxxxxxx"],
    message: "Hello World 👋🏻 via Sms"
  }, {
    enableDeliveryReport: true // Optional parameter
  });
console.log(result); // your message ID is in the result
}

ショート コード プログラムの brief ID にアクセスする

プログラムの簡易 ID は、Azure portal の [ショート コード] セクションにあります。

無料電話番号検証キャンペーンの簡易 ID にアクセスする

プログラムの簡易 ID は、Azure portal の規制のドキュメントのセクションにあります。

メール操作 ID にアクセスする

メールの送信またはメールの状態要求の送信に関するトラブルシューティングを行うときに、operation ID の提供が必要になる場合があります。 応答でこの値にアクセスできます。

var emailSendOperation = await emailClient.SendAsync(
    wait: WaitUntil.Completed,
    senderAddress: sender,
    recipientAddress: recipient,
    subject: subject,
    htmlContent: htmlContent);

/// Get the OperationId so that it can be used for tracking the message for troubleshooting
Console.WriteLine($"Email operation id = {emailSendOperation.Id}");

SDK の呼び出しにおけるサポート ファイルへのアクセス

SDK を呼び出すと、ログ ファイルにアクセスするための便利なメソッドが提供されます。 これらのファイルは、Microsoft のサポート スペシャリストやエンジニアにとって大変有用なものとなりえます。 問題を検出したときに、これらのログを収集することをお勧めします。

呼び出しログを有効にしてアクセスする

[JavaScript]

Azure Communication Services Calling SDK は、内部的に @azure/logger ライブラリを使用してログ記録を制御します。

ログ出力レベルを構成するには、@azure/logger パッケージの setLogLevel メソッドを使用します。 ロガーを作成し、次のように CallClient コンストラクターに渡します。

import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });

AzureLogger を使用して、AzureLogger.log メソッドをオーバーライドすると、Azure SDK からのログ出力をリダイレクトできます。

ブラウザー コンソール、ファイル、バッファにログを記録したり、独自のサービスに送信したりすることができます。 ログをネットワーク経由で独自サービスに送信する場合は、ブラウザーのパフォーマンスに悪影響が生じるため、ログ行ごとに要求を送信しないでください。 代わりに、ログ行を蓄積し、バッチで送信します。

// Redirect log output
AzureLogger.log = (...args) => {
    // To console, file, buffer, REST API, etc...
    console.log(...args); 
};

ネイティブ SDK (Android/iOS)

Android、iOS、Windows の場合、Azure Communication Services Calling SDK によりログ ファイルへのアクセスが提供されます。

Calling ネイティブ SDK については、「ログ ファイルへのアクセスのチュートリアル」を参照してください

UI ライブラリ (Android、iOS)

Android または iOS 用の Azure Communication Services UI ライブラリをお使いの場合は、組み込みのサポート フォームを使用してユーザー フィードバックを募ることができます。

Calling UI サポート フォームのサポート機能の詳細については、サポート フォーム統合のチュートリアルを参照してください。 このドキュメントでは、必要なイベント ハンドラーを追加し、サポート情報を一元的に保存するための基本的なクライアント/サーバー実装を作成する方法について説明します。 このガイドでは、組織で使用されるサポート サービスと統合する手順について説明されています。

ACS 統合でのエンド ツー エンドのサポート フローの構築

Calling SDK と Calling UI SDK のどちらを使用しているかに関係なく、顧客にサポートを提供することは、堅牢な統合における重要な要素です。 次のドキュメントでは、サポート フィードバック ループの各ポイントでの重要な考慮事項を示し、詳細を確認すべきポイントを紹介します。

ユーザー サポートの提供

Microsoft Entra 情報の検索

• ディレクトリ ID を取得しています
• アプリケーション ID を取得しています
• ユーザー ID を取得しています

ディレクトリ ID を取得しています

ディレクトリ (テナント) ID を見つけるには、次の手順に従います。

1. Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。

2. 左側のウィンドウから、[Microsoft Entra ID] を選択します。

3. Microsoft Entra ID の [概要] ページでディレクトリ (テナント) ID をコピーし、アプリケーション コードに保存します。

   

アプリケーション ID を取得しています

アプリケーション ID を見つけるには、次の手順に従います。

1. Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。

2. 左側のウィンドウから、[Microsoft Entra ID] を選択します。

3. Microsoft Entra ID の [アプリの登録] から、アプリケーションを選択します。

4. アプリケーション ID をコピーし、アプリケーション コードに保存します。

   

   ディレクトリ (テナント) ID は、アプリケーションの概要ページでも確認できます。

ユーザー ID を取得しています

ユーザー ID を見つけるには、次の手順に従います。

1. Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。

2. 左側のウィンドウから、[Microsoft Entra ID] を選択します。

3. Microsoft Entra ID の [ユーザー] から、ユーザーを選択します。

4. Microsoft Entra ユーザーの [プロファイル] ページで、オブジェクト IDをコピーし、アプリケーション コードに保存します。

   

変更できないリソース ID の取得

状況に応じて、Communication Service リソースの変更できないリソース ID を指定する必要があります。 これを見つけるには、次の手順に従います。

1. Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。
2. Communication Service リソースを開きます。
3. 左側のウィンドウから、[概要] を選択し、JSON ビューに切り替えます
4. [リソース JSON] ページの immutableResourceId 値をコピーし、サポート チームに渡してください。

Teams ユーザーのための Azure Communication Services サポートを使用するための Teams ライセンス適格性の検証

Teams ユーザーのための Azure Communication Services サポートを使用するための Teams ライセンス適格性を検証するには、2 つの方法があります。

• Teams Web クライアントを使用した検証
• Microsoft Graph API を使用して現在の Teams ライセンスを確認する

Teams Web クライアントを使用した検証

Teams Web クライアント経由で Teams ライセンス適格性を確認するには、次の手順に従います。

1. ブラウザーを開いて Teams Web クライアントに移動します。
2. 有効な Teams ライセンスを持つ資格情報でサインインします。
3. 認証が成功し、あなたが https://teams.microsoft.com/ ドメインの中にいる場合、あなたの Teams ライセンスは適格です。 認証に失敗する場合や https://teams.live.com/v2/ ドメインにリダイレクトされる場合、あなたの Teams ライセンスは Teams ユーザーのための Azure Communication Services サポートを使用する資格がありません。

Microsoft Graph API を使用して現在の Teams ライセンスを確認する

licenseDetails Microsoft Graph API を使用すると、ユーザーに割り当てられているライセンスが返されるので、現在の Teams ライセンスを確認できます。 Graph エクスプローラー ツールを使用して、ユーザーに割り当てられたライセンスを表示するには、次の手順に従います。

1. ブラウザーを開き、Graph エクスプローラー に移動します

2. Graph エクスプローラーに資格情報を使用してサインインします。

3. クエリ ボックスに次の API を入力して、[クエリの実行] をクリックします。

   https://graph.microsoft.com/v1.0/me/licenseDetails
   

   

   または、次の API を使用してユーザー ID を指定して、特定のユーザーに対してクエリをすることもできます。

   https://graph.microsoft.com/v1.0/users/{id}/licenseDetails
   

4. [応答プレビュー] ペインに出力が次のように表示されます。

   ここに示されている応答オブジェクトは、読みやすくするために短縮されている可能性があります。

   {
       "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('071cc716-8147-4397-a5ba-b2105951cc0b')/assignedLicenses",
       "value": [
           {
               "skuId": "b05e124f-c7cc-45a0-a6aa-8cf78c946968",
               "servicePlans":[
                   {
                       "servicePlanId":"57ff2da0-773e-42df-b2af-ffb7a2317929",
                       "servicePlanName":"TEAMS1",
                       "provisioningStatus":"Success",
                       "appliesTo":"User"
                   }
               ]
           }
       ]
   }
   

5. プロパティ servicePlanName に対象となる Teams ライセンス表のいずれかの値があるライセンスの詳細を見つける

関連記事

• Azure Communication Services PSTN 通話エラーのトラブルシューティング。
• Calling SDK、Call Automation SDK、PSTN、Chat SDK、SMS SDK の通話終了応答コードのトラブルシューティング。
• 音声とビデオ、チャット、メール、Network Traversal、レコーディング、SMS、Call Automation のログにアクセスします。
• メトリック。
• サービスの制限。