你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 通信服务中的故障排除

项目
02/20/2025

本文会帮助你排查 Azure 通信服务解决方案中可能会遇到的问题。如果要排查短信故障，可以使用 Azure 事件网格启用送达报告以捕获短信送达详情。

检查 Azure 通信服务运行状况

可以在 Azure 服务运行状况门户上查看 Azure 通信服务解决方案的运行状况。如果遇到 Azure 通信服务解决方案问题，请首先检查服务运行状况门户。然后，可以在致电支持人员或花时间进行故障排除之前，确定该问题是否是有解决方法的众所周知的问题。

Azure 服务运行状况门户提供正在使用的 Azure 服务和区域的运行状况的个性化视图。服务运行状况门户是查找中断、计划内维护活动和其他运行状况建议的最佳场所。你登录后，已经过身份验证的服务运行状况体验知道你当前使用哪些服务和资源。

使用服务运行状况的最佳方法是，设置服务运行状况警报，以便系统通过你首选的通信通道通知你。你会收到有关服务问题、计划内维护或影响 Azure 服务和区域的其他更改的通知。

如果无法登录服务运行状况门户，则可使用面向公众的“Azure 状态”页来检查已知问题。 Azure 状态概述从“Azure 状态”提供 Azure 服务和区域的全局视图。

对于广泛发生的事件，状态页是一个很好的参考。我们建议当前 Azure 用户查看经身份验证的 Azure 服务运行状况门户，以随时了解 Azure 事件和维护情况。已经过身份验证的 Azure 服务运行状况体验知道你当前使用哪些服务和资源。

当 Azure 通信服务发生中断，影响服务级别协议 (SLA) 中使用的指标时，该服务会在 Azure 服务运行状况门户和 Azure 状态中生成通知。有关 Azure 通信服务 SLA 的详细信息，请参阅服务级别协议。

通常情况下，当任何 Azure 通信服务 API 在一段持续时间内返回超过 3% 的已接收 API 调用的不可重试错误时，就会发生中断。

建议学习如何实施灾难恢复计划和高可用性策略。有关详细信息，请参阅 Azure 应用程序的灾难恢复和高可用性。

获取帮助

我们鼓励开发人员提交问题、建议功能以及报告问题。有关详细信息，请参阅专用支持和帮助选项页。

为了帮助你排查某些问题，可能需要以下一条或多条信息：

MS-CV ID：排查通话和消息问题。
通话 ID：标识 Azure 通信服务通话。
短信 ID：标识短信。
短代码计划简报 ID：标识短代码计划简报申请。
免费电话验证活动概要 ID：标识免费电话验证活动概要申请。
电子邮件 ID：标识“发送电子邮件”请求。
相关 ID：标识使用通话自动化发出的相关请求。
呼叫日志：使用该详细信息排查通话和网络问题。

有关限制和局限性的详细信息，请参阅服务限制。

获取 MS-CV ID

在初始化 SDK 时，可以通过在 clientOptions 对象实例中配置诊断来访问 MS-CV ID。可为任何 Azure SDK 配置诊断，包括聊天、标识和 VoIP 通话。

客户端选项示例

以下代码片段演示的是诊断配置。为 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)

使用访问 ID 实现通话自动化

排查通话自动化 SDK 出现的问题（如通话管理或录制问题）时，需要收集有助于识别失败通话或操作的 ID。可以提供以下两个 ID 之一：

API 响应标头中的 ID。找到字段 X-Ms-Skype-Chain-Id。
应用程序在执行操作后收到的回叫事件中的 ID。例如，使用 CallConnected 或 PlayFailed 查找相关 ID。

。

除了其中一个 ID 之外，还需要提供有关失败用例的详细信息以及发生故障的时间戳。

访问客户端呼叫 ID

排查语音或视频通话故障时，可能需要提供 call ID。通过 call 对象的 id 属性访问此值。

重要

call ID 是唯一的并标识特定通话。对于该通话的所有参与者，call ID 是相同的。 call 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())

获取短信 ID

对于短信问题，可以从响应对象中收集消息 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
}

访问短代码计划概要 ID

在 Azure 门户中的“短代码”部分查找计划简报 ID。

屏幕截图显示短代码计划概要 ID。

获取免费电话验证活动概要 ID

在 Azure 门户上的“法规文档”部分查找计划简报 ID。

屏幕截图显示免费电话验证市场活动简报 ID。

获取电子邮件操作 ID

排查电子邮件发送状态或电子邮件状态请求的问题时，可能需要提供操作 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

通话 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 通信服务通话 SDK 提供对日志文件的访问权限。

有关通话本机 SDK 的信息，请参阅日志文件访问教程。

UI 库（Android、iOS）

如果使用适用于 Android 或 iOS 的 Azure 通信服务 UI 库，可以通过内置支持表单征求用户反馈。

有关通话 UI 支持表单的支持功能的详细信息，请参阅支持表单集成教程。本文介绍如何添加必要的事件处理程序和创建用于集中存储支持信息的基本客户端/服务器实现。本文介绍与组织使用的支持服务集成的路径。

在 ACS 集成中构建端到端支持流

无论是使用通话 SDK 还是通话 UI SDK，向客户提供支持都是任何可靠集成的重要组成部分。

提供用户支持一文重点介绍了支持反馈循环中每个时间点的重要注意事项，并提供了了解更多信息的出发点。

查找 Microsoft Entra 信息

使用以下过程查找 Microsoft Entra 信息。

获取目录 ID

若要查找目录（租户）ID，请执行下列步骤：

登录到 Azure 门户。
在服务菜单上，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 的“概述”页中，复制目录 ID（租户 ID）并将其存储在应用程序代码中。

获取应用程序 ID

若要查找应用程序 ID，请执行下列步骤：

登录到 Azure 门户。
在服务菜单上，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 中的“应用注册”中，选择应用程序。
复制“应用程序(客户端) ID”并将其存储在应用程序代码中。

还可以在应用程序的“概述”页上找到目录（租户）ID。

获取用户 ID

若要查找用户 ID，请执行下列步骤：

登录到 Azure 门户。
在服务菜单上，选择“Microsoft Entra ID”。
在 Microsoft Entra ID 中的“用户”中，选择用户。
在 Microsoft Entra 用户的“配置文件”页上，复制“对象 ID”并将其存储在应用程序代码中。

获取不可变资源 ID

有时，你还需要提供 Azure 通信服务资源的不可变资源 ID。若要查找此 ID，请执行下列步骤：

登录到 Azure 门户。
打开 Azure 通信服务资源。
在服务菜单上，选择“概述”并切换到“JSON 视图”。
在“资源 JSON”页上，复制 immutableResourceId 值，并将其提供给支持团队。

验证 Teams 许可证是否符合资格，使 Teams 用户可以使用 Azure 通信服务支持

可通过两种方法验证 Teams 许可证是否符合资格，使 Teams 用户可以使用 Azure 通信服务支持。

通过 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 查找当前的 Teams 许可证。 Microsoft 图形 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 许可证表中的一个值。

排查 Azure 通信服务 PSTN 通话故障。
对通话 SDK、通话自动化 SDK、PSTN、聊天 SDK 和短信 SDK 的通话结束响应代码进行故障排除。
语音和视频、聊天、电子邮件、网络遍历、录制、短信和通话自动化的访问日志。
指标
服务限制。

通过