你当前正在访问 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 | 因未知错误/故障,消息发送失败 | 请尝试重新发送消息 |
相关信息
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈