你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 通信服务中的故障排除
本文档将帮助你解决通信服务解决方案中可能会遇到的问题。 如果要排查短信故障，可以使用事件网格启用送达报告以捕获短信送达详情。
获取帮助
我们鼓励开发人员提交问题、建议功能以及报告问题。 为协助你获得帮助，我们提供了一个专用的支持和帮助选项页，其中列出了支持选项。
为了帮助你对某些类型的问题进行故障排除，系统可能会要求你提供以下信息：
- MS-CV ID：此 ID 用于对通话和消息进行故障排除。
- 通话 ID：此 ID 用于标识通信服务通话。
- 短信 ID：此 ID 用于标识短信。
- 短代码计划概要 ID：此 ID 用于标识短代码计划概要申请。
- 免费电话验证活动概要 ID：此 ID 用于标识免费电话验证活动概要应用程序。
- 电子邮件 ID：此 ID 用于标识“发送电子邮件”请求。
- 关联 ID：此 ID 用于标识使用“调用自动化”发出的请求。
- 通话日志：这些日志包含可用于排查通话和网络问题的详细信息。
另请参阅服务限制文档，详细了解相关限制。
获取 MS-CV ID
在初始化 SDK 时，可以通过在 clientOptions 对象实例中配置诊断来获取 MS-CV ID。 可以为任何 Azure SDK（包括聊天、标识和 VoIP 呼叫）配置诊断。
客户端选项示例
以下代码片段演示的是诊断配置。 在启用诊断的情况下使用这些 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) });
“调用自动化”所需的访问 ID
排查通话自动化 SDK 出现的问题（如通话管理或录制问题）时，将需要收集有助于识别失败通话或操作的 ID。 可以提供此处提到的两个 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)
获取短信 ID
对于短信问题，可以从响应对象中收集消息 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
}
访问短代码计划概要 ID
计划概要 ID 可以在 Azure 门户的“短代码”边栏选项卡中找到。
获取免费电话验证活动概要 ID
计划概要 ID 可以在 Azure 门户的“法规文档”边栏选项卡中找到。
获取电子邮件操作 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 通信服务通话 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 通信服务通话 SDK 提供对日志文件的访问权限。
有关通话本机 SDK，请参阅日志文件访问教程
UI 库（Android、iOS）
如果使用适用于 Android 或 iOS 的 Azure 通信服务 UI 库，可以通过内置支持表单征求用户反馈。
有关如何使用通话 UI 支持表单的支持功能的详细信息，请参阅支持表单集成教程。 此文档将指导你添加必要的事件处理程序，并创建基本客户端/服务器实现以集中存储支持信息。 此指南旨在指导你完成与组织使用的支持服务的集成。
在 ACS 集成中构建端到端支持流
无论是使用通话 SDK 还是通话 UI SDK，向最终用户提供支持都是任何可靠集成的重要组成部分。 以下文档重点介绍了支持反馈循环中每个时间点的重要注意事项，并提供了了解更多信息的出发点。
查找 Microsoft Entra 信息
- 获取目录 ID
- 获取应用程序 ID
- 获取用户 ID
获取目录 ID
若要查找 Directory（租户）ID，请执行下列步骤：
导航到 Azure 门户并使用凭据登录到 Azure 门户。
在左窗格中，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 的“概述”页中，复制 Directory（租户）ID 并将其存储在应用程序代码中。
获取应用程序 ID
若要查找应用程序 ID，请执行下列步骤：
导航到 Azure 门户并使用凭据登录到 Azure 门户。
在左窗格中，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 中的“应用注册”中，选择应用程序。
复制“应用程序 ID”并将其存储在应用程序代码中。
目录（租户）ID 也可以在应用程序概述页中找到。
获取用户 ID
若要查找用户 ID，请执行下列步骤：
导航到 Azure 门户并使用凭据登录到 Azure 门户。
在左窗格中，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 中的“用户”中，选择用户。
在 Microsoft Entra 用户的“配置文件”页中，复制“对象 ID”并将其存储在应用程序代码中。
获取不可变资源 ID
有时，你还需要提供通信服务资源的不可变资源 ID。 若要查找此 ID，请执行下列步骤：
- 导航到 Azure 门户并使用凭据登录到 Azure 门户。
- 打开通信服务资源。
- 在左窗格中，选择“概述”，然后切换到“JSON 视图”
- 从“资源 JSON”页复制
immutableResourceId值，并将其提供给支持团队。
验证 Teams 许可证资格，以便使用对 Teams 用户的 Azure 通信服务支持
可通过两种方法验证 Teams 许可证资格，以便使用对 Teams 用户的 Azure 通信服务支持：
- 通过 Teams Web 客户端进行验证
- 通过 Microsoft 图形 API 检查当前 Teams 许可证
通过 Teams Web 客户端进行验证
若要通过 Teams Web 客户端验证 Teams 许可证资格，请按以下步骤操作：
- 打开浏览器并导航到 Teams Web 客户端。
- 使用具有有效 Teams 许可证的凭据登录。
- 如果身份验证成功，并且你仍在 https://teams.microsoft.com/ 域中，则 Teams 许可证符合资格。 如果身份验证失败，或者你被重定向到 https://teams.live.com/v2/ 域，则 Teams 许可证不符合使用对 Teams 用户的 Azure 通信服务支持的资格。
通过 Microsoft 图形 API 检查当前 Teams 许可证
可以使用 licenseDetails Microsoft Graph API 找到当前 Teams 许可证，该 API 返回分配给用户的许可证。 按照以下步骤使用 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 许可证表中的一个值
呼叫 SDK 错误代码
Azure 通信服务呼叫 SDK 使用以下错误代码，你可以通过这些错误代码来排查呼叫问题。 呼叫结束后，这些错误代码通过 call.callEndReason 属性公开。
| 错误代码 | 说明 | 采取的操作 |
|---|---|---|
| 403 | 被禁止/身份验证失败。 | 请确保通信服务令牌有效且未过期。 |
| 404 | 找不到呼叫。 | 确保要呼叫的电话（或要加入的电话）存在。 |
| 408 | 呼叫控制器超时。 | 等待来自用户终结点的协议消息时呼叫控制器超时。 确保客户端已连接且可用。 |
| 410 | 本地媒体堆栈或媒体基础结构错误。 | 请确保在受支持的环境中使用最新的 SDK。 |
| 430 | 无法将消息传递到客户端应用程序。 | 请确保客户端应用程序正在运行而且可用。 |
| 480 | 未注册远程客户端终结点。 | 确保远程终结点可用。 |
| 481 | 无法处理传入呼叫。 | 通过 Azure 门户提交支持请求。 |
| 487 | 呼叫被取消、本地被拒绝，由于终结点不匹配问题而结束，或无法生成媒体产品/服务。 | 预期行为。 |
| 490、491、496、497、498 | 本地终结点网络问题。 | 检查网络。 |
| 500、503、504 | 通信服务基础结构错误。 | 通过 Azure 门户提交支持请求。 |
| 603 | 全球呼叫被远程通信服务参与者拒绝 | 预期行为。 |
调用自动化 SDK 错误代码
以下错误代码由调用自动化 SDK 公开。
| 错误代码 | 说明 | 要执行的操作 |
|---|---|---|
| 400 | 无效的请求 | 输入请求无效。 查看错误消息以确定哪个输入不正确。 |
| 400 | 播放失败 | 确保音频文件为 WAV、16KHz、Mono，并确保文件 URL 可公开访问。 |
| 400 | 识别失败 | 请检查错误消息。 如果失败原因是超时或操作已被取消，将突出显示消息。 有关错误代码和消息的详细信息，请查看收集用户输入操作指南。 |
| 401 | 未授权 | HMAC 身份验证失败。 验证用于创建 CallAutomationClient 的连接字符串是否正确。 |
| 403 | 已禁止 | 请求被禁止。 确保可以访问尝试访问的资源。 |
| 404 | 找不到资源 | 尝试执行操作的调用不存在。 例如，转移已断开连接的调用。 |
| 429 | 请求太多 | 在 Retry-After 标头中建议的延迟后重试，然后以指数形式退避。 |
| 500 | 内部服务器错误 | 在延迟一段时间后重试。 如果该问题仍然存在，请提交支持票证。 |
| 500 | 播放失败 | 通过 Azure 门户提交支持请求。 |
| 500 | 识别失败 | 检查错误消息并确认音频文件格式有效（WAV、16KHz、Mono），如果文件格式有效，则通过 Azure 门户提交支持请求。 |
| 502 | 网关错误 | 使用全新 http 客户端在延迟一段时间后重试。 |
排查某些问题时，请考虑以下提示。
- 应用程序未收到 IncomingCall 事件网格事件：确保在创建事件订阅时已使用事件网格验证应用程序终结点。 如果验证成功，事件订阅的预配状态将被标记为成功。
- 收到错误“字段 CallbackUri 无效”：调用自动化不支持 HTTP 终结点。 请确保提供的回调 URL 支持 HTTPS。
- PlayAudio 操作不播放任何内容：音频文件目前仅支持 Wave 文件 (.wav) 格式。 Wave 文件中的音频内容必须是单声道、16 位采样，采样率为 16,000 (16KHz)。
- PSTN 终结点上的操作不起作用：CreateCall、转移、AddParticipant 和重定向到电话号码需要你在操作请求中设置 SourceCallerId。 除非使用的是直接路由，否则源调用方 ID 应是通信服务资源拥有的电话号码，以便操作成功。
请参阅本文，了解产品团队正在跟踪的任何已知问题。
聊天 SDK 错误代码
Azure 通信服务聊天 SDK 使用以下错误代码，你可以通过这些错误代码来排查聊天问题。 错误代码通过错误响应中的 error.code 属性公开。
| 错误代码 | 说明 | 采取的操作 |
|---|---|---|
| 401 | 未授权 | 请确保通信服务令牌有效且未过期。 |
| 403 | 已禁止 | 确保请求的发起方有权访问该资源。 |
| 429 | 请求太多 | 确保客户端应用程序以用户友好的方式处理此方案。 如果此错误持续存在，请提交支持请求。 |
| 503 | 服务不可用 | 通过 Azure 门户提交支持请求。 |
SMS 错误代码
Azure 通信服务 SMS SDK 使用以下错误代码，你可以通过这些错误代码来排查 SMS 问题。 错误代码通过短信发送报告中的“DeliveryStatusDetails”字段公开。
| 错误代码 | 说明 | 采取的操作 |
|---|---|---|
| 2000 | 消息已成功发送 | |
| 4000 | 因欺诈检测，消息被拒绝 | 请确保不超过你的号码所允许的最大消息数 |
| 4001 | 因源/发送号码格式无效，消息被拒绝 | 请确保接收号码采用 E.164 格式，发送号码采用 E.164 或短代码格式 |
| 4002 | 因目标/接收号码格式无效，消息被拒绝 | 请确保接收号码采用 E.164 格式 |
| 4003 | 因目标不受支持，消息发送失败 | 请检查尝试发送到的目标是否受支持 |
| 4004 | 因目标/接收号码不存在，消息发送失败 | 请确保要发送到的接收号码有效 |
| 4005 | 消息被目标运营商阻止 | |
| 4006 | 无法接通目标/接收号码 | 请尝试稍后重新发送消息 |
| 4007 | 目标/接收号码已选择不接收你的消息 | 将目标/接收号码标记为已选择不接收，以便不再试图向该号码发送消息 |
| 4008 | 已超出配置文件允许的最大消息数 | 请确保不超过你的号码所允许的最大消息数，或使用队列对消息进行批处理 |
| 4009 | 消息被 Microsoft 权利系统拒绝 | 这最常发生在检测到欺诈活动的情况下。 请联系支持部门以了解详细信息 |
| 4010 | 由于未验证免费号码，邮件被阻止 | 查看未经验证的发送限制并尽快提交免费验证 |
| 5000 | 消息发送失败。 请联系 Microsoft 支持团队了解更多详细信息 | 通过 Azure 门户提交支持请求 |
| 5001 | 因应用程序/系统暂时不可用，消息发送失败 | |
| 5002 | 运营商不支持送达报告 | 这最常发生在运营商不支持送达报告的情况下。 由于消息可能已送达，因此不需要执行任何操作。 |
| 9999 | 因未知错误/故障，消息发送失败 | 请尝试重新发送消息 |