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

[アーティクル]
03/19/2024

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

ヘルプの表示

開発者の皆さんは、ご質問の送信、機能のご提案、および問題のレポートに関してぜひご協力ください。ヘルプの利用を支援するために、サポートのオプションを一覧にしたサポートとヘルプのオプションの専用ページを用意しています。

特定の種類の問題のトラブルシューティングを支援するために、次の情報をおたずねする場合があります。

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

また、調整と制限事項の詳細については、「サービスの制限」に関するドキュメントを参照してください。

MS-CV ID にアクセスする

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

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

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

C#
Python

// 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 の 1 つに加えて、失敗したユースケースの詳細と、エラーが発生した日時のタイムスタンプを提供してください。

クライアント通話 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 を収集できます。

.NET

// 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 にアクセスする

プログラムの brief ID は、ショートコードブレードの Azure portal にあります。

ショートコードプログラムの brief ID を示すスクリーンショット

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

プログラムの brief ID は、規制ドキュメントブレードの Azure Portal にあります。

無料電話番号検証キャンペーンの簡易 ID を示すスクリーンショット。

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

電子メールまたは電子メールメッセージの状態要求の送信に関するトラブルシューティングを行うときに、operation ID を指定するように求められる場合があります。この値は応答から確認できます。

.NET

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.log メソッドをオーバーライドすることで、AzureLogger を使用して、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 を見つけるには、次の手順に従います。

Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。
左側のウィンドウから、[Microsoft Entra ID] を選択します。
Microsoft Entra ID の [概要] ページでディレクトリ (テナント) ID をコピーし、アプリケーションコードに保存します。

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

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

Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。
左側のウィンドウから、[Microsoft Entra ID] を選択します。
Microsoft Entra ID の [アプリの登録] から、アプリケーションを選択します。
アプリケーション ID をコピーし、アプリケーションコードに保存します。

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

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

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

Azure portal に移動し、資格情報を使用して Azure ポータルにサインインします。
左側のウィンドウから、[Microsoft Entra ID] を選択します。
Microsoft Entra ID の [ユーザー] から、ユーザーを選択します。
Microsoft Entra ユーザーの [プロファイル] ページで、オブジェクト IDをコピーし、アプリケーションコードに保存します。

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

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

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

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

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

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

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

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

ブラウザーを開いて Teams Web クライアントに移動します。
有効な Teams ライセンスを持つ資格情報でサインインします。
認証が成功し、あなたが 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 エクスプローラーツールを使用して、ユーザーに割り当てられたライセンスを表示するには、次の手順に従います。

ブラウザーを開き、Graph エクスプローラーに移動します
Graph エクスプローラーに資格情報を使用してサインインします。
クエリボックスに次の API を入力して、[クエリの実行] をクリックします。
```
https://graph.microsoft.com/v1.0/me/licenseDetails
```
または、次の API を使用してユーザー ID を指定して、特定のユーザーに対してクエリをすることもできます。
```
https://graph.microsoft.com/v1.0/users/{id}/licenseDetails
```

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

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

{
    "@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"
                }
            ]
        }
    ]
}

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

Calling SDK のエラーコード

Azure Communication Services の Calling SDK では、通話の問題のトラブルシューティングに役立つ次のエラーコードを使用します。これらのエラーコードは、通話の終了後に call.callEndReason プロパティを通じて公開されます。

エラーコード	説明	実行するアクション
403	禁止または認証エラー。	Communication Services トークンが有効であり、有効期限が切れていないことを確認します。
404	通話が見つかりません。	通話先の番号 (または参加している通話) が存在することを確認します。
408	通話コントローラーがタイムアウトしました。	ユーザーエンドポイントからのプロトコルメッセージの待機中に通話コントローラーがタイムアウトしました。クライアントが接続され、使用可能であることを確認します。
410	ローカルメディアスタックまたはメディアインフラストラクチャエラー。	サポートされている環境で最新の SDK を使用していることを確認します。
430	クライアントアプリケーションにメッセージを配信できません。	クライアントアプリケーションが実行されていて使用可能であることを確認します。
480	リモートクライアントエンドポイントが登録されていません。	リモートエンドポイントが使用可能であることを確認します。
481	着信通話の処理に失敗しました。	Azure portal からサポートリクエストを提出します。
487	エンドポイントの不一致の問題が原因で通話がキャンセルされたか、ローカルで拒否されたか、終了しました。または、メディアプランの生成に失敗しました。	想定されている動作です。
490、491、496、497、498	ローカルエンドポイントネットワークの問題。	ネットワークを確認します。
500、503、504	Communication Services インフラストラクチャエラー。	Azure portal からサポートリクエストを提出します。
603	Communication Services のリモート参加者によって、通話がグローバルに拒否されました。	想定されている動作です。

Call Automation SDK のエラーコード

Call Automation SDK によって、次のエラーコードが公開されています。

エラーコード	説明	実行するアクション
400	Bad request	入力要求が無効です。エラーメッセージを調べて、正しくない入力を確認します。
400	再生に失敗しました	オーディオファイルが WAV、16KHz、Mono であることを確認し、ファイル URL がパブリックにアクセスできることを確認します。
400	認識に失敗しました	エラーメッセージをご確認ください。この失敗がタイムアウトに達したためか、操作が取り消されたためか、メッセージで確認できます。エラーコードとメッセージの詳細については、ユーザー入力を収集するための攻略ガイドを参照してください。
401	権限がありません	HMAC 認証が失敗しました。 CallAutomationClient の作成に使われている接続文字列が正しいかどうかを確認します。
403	許可されていません	要求は禁止されています。アクセスしようとしているリソースへのアクセス権があることを確認します。
404	リソースが見つかりません	処理しようとしている通話は存在しません。たとえば、既に切断されている通話の転送。
429	Too many requests	Retry-After ヘッダーで提案されている遅延の後で再試行し、エクスポネンシャルバックオフを行います。
500	内部サーバーエラー	遅延後に再試行します。それでも解決しない場合は、サポートチケットを提出してください。
500	再生に失敗しました	Azure portal からサポートリクエストを提出します。
500	認識に失敗しました	エラーメッセージを確認し、オーディオファイル形式が有効 (WAV、16KHz、Mono) であることを確認します。ファイル形式が有効な場合は、Azure portal を通じてサポートリクエストを提出します。
502	Bad gateway	新しい http クライアントで遅延後に再試行します。

特定の問題をトラブルシューティングする場合は、次のヒントを検討してください。

アプリケーションが IncomingCall Event Grid イベントを取得していない: イベントサブスクリプションの作成時に、アプリケーションエンドポイントが Event Grid で検証されていることを確認します。検証が成功した場合、イベントサブスクリプションのプロビジョニング状態は成功としてマークされます。
エラー "フィールド CallbackUri が無効です" が発生する: Call Automation が HTTP エンドポイントをサポートしていません。指定したコールバック URL が HTTPS をサポートしていることを確認します。
PlayAudio アクションで何も再生されない: 現在、オーディオファイルでサポートされているのは Wave ファイル (.wav) 形式だけです。 Wave ファイルのオーディオコンテンツは、モノラル (1 チャンネル) で、16,000 (16KHz) サンプリングレートの 16 ビットサンプルである必要があります。
PSTN エンドポイントのアクションが機能していない: 電話番号への CreateCall、Transfer、AddParticipant、Redirect では、アクション要求で SourceCallerId を設定する必要があります。アクションが成功するには、ダイレクトルーティングを使っている場合を除き、ソース発信者 ID は Communication Services リソースによって所有されている電話番号である必要があります。

製品チームが追跡している既知の問題については、こちらの記事をご覧ください。

Chat SDK のエラーコード

Azure Communication Services の Chat SDK では、チャットの問題のトラブルシューティングに役立てるために次のエラーコードを使用しています。エラーコードは、エラー応答の error.code プロパティを通じて公開されます。

エラーコード	説明	実行するアクション
401	権限がありません	Communication Services トークンが有効であり、有効期限が切れていないことを確認します。
403	許可されていません	要求のイニシエーターがリソースへのアクセス権を持っていることを確認してください。
429	Too many requests	クライアント側アプリケーションで、このシナリオがユーザーフレンドリな方法で処理されていることを確認してください。エラーが解決しない場合は、サポートリクエストを提出してください。
503	サービス利用不可	Azure portal からサポートリクエストを提出します。

SMS エラーコード

Azure Communication Services の SMS SDK では、SMS の問題のトラブルシューティングに役立てるために次のエラーコードを使用しています。エラーコードは、SMS 配信レポートの "DeliveryStatusDetails" フィールドによって公開されます。

エラーコード	説明	実行するアクション
2,000	メッセージが正常に配信されました
4000	不正行為の検出によってメッセージが拒否されました	自分の番号に許可されているメッセージの最大数を超えていないことを確認します
4001	送信元/差出人番号の形式が無効なため、メッセージは拒否されました	宛先番号が E.164 形式で、差出人番号が E.164 形式またはショートコード形式であることを確認します
4002	送信先/宛先番号の形式が無効なため、メッセージは拒否されました	宛先番号が E.164 形式であることを確認します
4003	送信先がサポートされていないため、メッセージを配信できませんでした	送信先がサポートされているかどうかを確認します
4004	送信先/宛先番号が存在しないため、メッセージを配信できませんでした	送信先の番号が有効であることを確認します
4005	送信先の通信事業者によってメッセージがブロックされています
4006	送信先/宛先番号に到達できません	後でメッセージを再送信してください
4007	送信先/宛先番号によってメッセージの受信がオプトアウトされました	宛先/宛先番号をオプトアウトされたものとしてマークすることで、その後のメッセージの試行は行われません
4008	プロファイルで許可されているメッセージの最大数を超えました	自分の数値に許可されているメッセージの最大数を超えていないことを確認するか、キューを使用してメッセージをバッチ処理します
4009	Microsoft エンタイトルメントシステムによってメッセージが拒否されました	ほとんどの場合、これは不正なアクティビティが検出された場合に発生します。詳細については、サポートにお問い合わせください
4010	無料電話番号が検証されていないため、メッセージがブロックされた	未検証の送信制限を確認し、できるだけ早く無料電話番号の検証を送信してください
5000	メッセージを配信できませんでした。詳細については、Microsoft サポートチームにお問い合わせください	Azure portal からサポートリクエストを提出します
5001	アプリケーション/システムが一時的に利用できなくなったため、メッセージを配信できませんでした
5002	通信事業者は配信レポートをサポートしていません	ほとんどの場合、これは通信事業者が配信レポートをサポートしていない場合に発生します。メッセージが既に配信されている可能性があるため、アクションは必要ありません。
9999	不明なエラーが発生したため、メッセージを配信できませんでした	メッセージを再送信してみてください

音声とビデオ、チャット、メール、レコーディング、SMS、Call Automation のログにアクセスします。
SDK を呼び出すためのログファイル名 API
Metrics
サービスの制限