Azure 通信服务中的故障排除

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

获取帮助

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

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

• MS-CV 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) });

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 响应的标头中，找到字段 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())

获取短信 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

在 Azure 门户上的“短代码”部分查找计划概要 ID。

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

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

获取电子邮件操作 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 通过重写 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 信息

• 获取目录 ID
• 获取应用程序 ID
• 获取用户 ID

获取目录 ID

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

1. 导航到 Azure 门户并使用凭据登录到 Azure 门户。

2. 在左窗格中，选择“Microsoft Entra ID”。

3. 在 Microsoft Entra ID 的“概述”页中，复制 Directory（租户）ID 并将其存储在应用程序代码中。

   

获取应用程序 ID

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

1. 导航到 Azure 门户并使用凭据登录到 Azure 门户。

2. 在左窗格中，选择“Microsoft Entra ID”。

3. 在 Microsoft Entra ID 中的“应用注册”中，选择应用程序。

4. 复制“应用程序 ID”并将其存储在应用程序代码中。

   

   目录（租户）ID 也可以在应用程序概述页中找到。

获取用户 ID

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

1. 导航到 Azure 门户并使用凭据登录到 Azure 门户。

2. 在左窗格中，选择“Microsoft Entra ID”。

3. 在 Microsoft Entra ID 中的“用户”中，选择用户。

4. 在 Microsoft Entra 用户的“配置文件”页中，复制“对象 ID”并将其存储在应用程序代码中。

   

获取不可变资源 ID

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

1. 导航到 Azure 门户并使用凭据登录到 Azure 门户。
2. 打开通信服务资源。
3. 在左窗格中，选择“概述”，然后切换到“JSON 视图”
4. 从“资源 JSON”页复制 immutableResourceId 值，并将其提供给支持团队。

验证 Teams 许可证资格，以便使用对 Teams 用户的 Azure 通信服务支持

可通过两种方法验证 Teams 许可证资格，以便使用对 Teams 用户的 Azure 通信服务支持：

• 通过 Teams Web 客户端进行验证
• 通过 Microsoft 图形 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 通信服务支持的资格。

通过 Microsoft 图形 API 检查当前 Teams 许可证

可以使用 licenseDetails Microsoft Graph API 找到当前 Teams 许可证，该 API 返回分配给用户的许可证。 按照以下步骤使用 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 通信服务 PSTN 通话故障。
• 对通话 SDK、通话自动化 SDK、PSTN、聊天 SDK 和短信 SDK 的通话结束响应代码进行故障排除。
• 语音和视频、聊天、电子邮件、网络遍历、录制、短信和通话自动化的访问日志。
• 指标
• 服务限制。