通过

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

呼叫摘要日志架构

  • 项目

呼叫摘要日志包含有助于标识所有呼叫关键值属性的数据。 为呼叫中的每个 participantId（在对等 [P2P] 呼叫的情况下为 endpointId）值创建不同的呼叫摘要日志。

对于呼叫中的每个参与者，通信服务都会创建一个不同的呼叫摘要日志。 如果有人重新加入呼叫，则该参与者将具有相同的 EndpointId 值，但具有不同的 ParticipantId 值。 然后，该终结点可能会有两个呼叫摘要日志。

如何使用呼叫日志

建议在 Log Analytics 资源中收集所有可用的呼叫日志，以便监视呼叫使用情况和改进通话质量，并在我们发布新日志时从 Azure 通信服务接收这些日志。

可使用两个主要工具来监视通话并提高通话质量。

建议使用“语音和视频见解”仪表板来启动任何质量调查，并根据需要使用通话诊断，以在需要精细的详细信息时浏览单次呼叫。

数据概念

重要

若要分析日志，必须收集这些日志。 若要了解详细信息，请参阅：如何存储日志？

除非启用这些特定的诊断设置，否则 Azure 不会存储呼叫日志数据。 呼叫数据不可追溯。 创建诊断设置后，将累积数据。

数据定义

呼叫摘要日志架构

重要

呼叫摘要日志中的参与者信息因参与者租户而异。 如果参与者与通信服务资源不在同一租户内（也称为跨租户），则会修订 SDK 版本和 OS 版本。 跨租户的参与者分类为外部用户，他们由资源租户邀请加入呼叫并在呼叫期间协作。

下表介绍了每个属性。

properties 说明
time 生成日志时的时间戳 (UTC)。
operationName 与日志记录相关联的操作。
operationVersion 如果通过 API 执行 operationName 操作，则 api-version 值与该操作关联。 如果没有任何 API 对应于此操作，则此版本表示操作的版本，以防与该操作关联的属性将来发生更改。
category 事件的日志类别。 此属性是可以在资源上启用或禁用日志的粒度。 出现在事件的 properties blob 中的属性与日志类别和资源类型中的属性相同。
correlationId 呼叫的唯一 ID。 它可从单次呼叫期间连接的所有参与者和终结点中标识相关事件，并且可用于联接来自不同日志的数据。 如果需要通过 Microsoft 打开支持案例，则可以使用 correlationId 值轻松标识你要排查故障的呼叫。
identifier 用户的唯一 ID。 该标识可以是 Azure 通信服务用户、Microsoft Entra 用户 ID、Teams 匿名用户 ID 或 Teams 机器人 ID。 你可使用此 ID 来关联不同日志中的用户事件。
callStartTime 呼叫开始的时间戳，获取依据为任何终结点第一次尝试连接的时间。
callDuration 呼叫的持续时间，以秒为单位，获取依据为两个终结点之间第一次尝试连接的时间和最后一次连接结束的时间。
callType 呼叫的类型。 它包含 "P2P" 或 "Group"。 "P2P" 呼叫是仅在两个非服务器终结点之间的直接 1:1 连接。 "Group" 呼叫是具有两个以上终结点的呼叫，或是在连接之前作为 "Group" 而创建的呼叫。
teamsThreadId Teams 会话 ID。 仅当呼叫组织为 Teams 会议时，此 ID 才有意义。 然后，它代表 Microsoft Teams 和 Azure 通信服务之间的互操作性用例。

此 ID 在操作日志中是公开的。 你还可以通过聊天 API 获取此 ID。
participantId 生成此 ID 是用于表示 "Participant" 终结点 (endpointType = "Server") 与服务器之间的双向连接。 当 callType = "P2P" 时，两个终结点之间为直接连接，不会生成 participantId 值。
participantStartTime 参与者第一次连接尝试开始的时间戳。
participantDuration 每个参与者连接的持续时间，以秒为单位，从 participantStartTime 到连接结束的时间戳为止。
participantEndReason 参与者连接结束的原因。 它包含 SDK 为每个 participantId 值发出的呼叫 SDK 错误代码（如果相关）。
endpointId 表示连接到呼叫的各个终结点的唯一 ID，其中 endpointType 定义终结点类型。 当该值为 null 时，连接的实体是通信服务服务器 (endpointType = "Server")。

对于本机客户端，有时可为跨多个呼叫 (correlationId) 的同一用户保留 endpointId 值。 endpointId 值的数量将决定呼叫摘要日志的数量。 对于每个 endpointId 值，都会创建一个单独的摘要日志。
endpointType 该值用于描述连接到呼叫的各个终结点的属性。 可以包含 "Server"、"VOIP"、"PSTN"、"BOT" 或 "Unknown"。
sdkVersion 各个相关终结点使用的通信服务呼叫 SDK 版本的版本字符串（例如，"1.1.00.20212500"）。
osVersion 表示每个终结点设备的操作系统和版本的字符串。
participantTenantId 与参与者标识关联的 Microsoft 租户的 ID。 该租户可以是拥有 Azure 通信服务资源的 Azure 租户，也可以是 Microsoft 365 标识的 Microsoft 租户。 此字段用于指导跨租户编修。
participantType 对参与者的描述，即其客户端（Azure 通信服务或团队）及其标识（Azure 通信服务或 Microsoft 365）的组合。 可能的值包括：Azure 通信服务（Azure 通信服务标识和 Azure 通信服务 SDK）、Teams（Teams 标识和 Teams 客户端）、作为 Teams 外部用户的 Azure 通信服务（Teams 呼叫或会议中的 Azure 通信服务标识和 Azure 通信服务 SDK）、作为 Microsoft 365 用户的 Azure 通信服务（Microsoft 365 标识和 Azure 通信服务客户端）和 Teams 语音应用。
pstnParticipantCallType 表示 PSTN 参与者的类型和方向，包括紧急呼叫、直接路由、转移、转接等。
ParticipantEndSubCode 表示 SDK 为每个 participantId 值发出（相关时）的通话 SDK 错误子代码。
ResultCategory 表示结束通话的参与者的类别。 它可以是以下四个值之一：Success、ExpectedError、UnexpectedClientError、UnexpectedServerError。
DiagnosticOptions 此值允许开发人员将自定义标记附加到其客户端遥测，然后可在“呼叫诊断”部分查看这些标记。 这有助于更有效地识别和排查问题。 若要了解如何向此值添加自定义标记，请参阅有关如何将自定义标记添加到客户端遥测的教程

错误代码

participantEndReason 属性包含从一组呼叫 SDK 错误代码中获取的值。 你可以参考这些代码，以便针对每个终结点排查呼叫过程中检测到的问题。 请参阅对通话 SDK、通话自动化 SDK、PSTN、聊天 SDK 和短信 SDK 的通话结束响应代码进行故障排除。

各种呼叫类型的示例数据

注意

在本文中，P2P 和群组呼叫默认都位于同一租户内。 在整篇文章中，跨租户的所有呼叫方案都会相应地指出。

P2P 呼叫

以下是 P2P 呼叫中所有日志的共享字段：

"time":                     "2021-07-19T18:46:50.188Z",
"resourceId":               "SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/ACS-TEST-RG/PROVIDERS/MICROSOFT.COMMUNICATION/COMMUNICATIONSERVICES/ACS-PROD-CCTS-TESTS",
"correlationId":            "aaaa0000-bb11-2222-33cc-444444dddddd",

呼叫摘要日志

呼叫摘要日志共享操作和类别信息：

"operationName":            "CallSummary",
"operationVersion":         "1.0",
"category":                 "CallSummary",

以下是 VoIP 用户 1 的呼叫摘要：

"properties": {
    "identifier":               "acs:61fddbe3-0003-4066-97bc-6aaf143bbb84_0000000b-4fee-66cf-ac00-343a0d003158",
    "callStartTime":            "2021-07-19T17:54:05.113Z",
    "callDuration":             6,
    "callType":                 "P2P",
    "teamsThreadId":            "null",
    "participantId":            "null",    
    "participantStartTime":     "2021-07-19T17:54:06.758Z",
    "participantDuration":      "5",
    "participantEndReason":     "0",
    "endpointId":               "570ea078-74e9-4430-9c67-464ba1fa5859",
    "endpointType":             "VoIP",
    "sdkVersion":               "1.0.1.0",
    "osVersion":                "Windows 10.0.17763 Arch: x64"
}

以下是 VoIP 用户 2 的呼叫摘要：

"properties": {
    "identifier":               "acs:7af14122-9ac7-4b81-80a8-4bf3582b42d0_06f9276d-8efe-4bdd-8c22-ebc5434903f0",
    "callStartTime":            "2021-07-19T17:54:05.335Z",
    "callDuration":             6,
    "callType":                 "P2P",
    "teamsThreadId":            "null",
    "participantId":            "null",
    "participantStartTime":     "2021-07-19T17:54:06.335Z",
    "participantDuration":      "5",
    "participantEndReason":     "0",
    "endpointId":               "a5bd82f9-ac38-4f4a-a0fa-bb3467cdcc64",
    "endpointType":             "VoIP",
    "sdkVersion":               "1.1.0.0",
    "osVersion":                "null"
}

以下是 VoIP 用户 1 的跨租户呼叫摘要日志：

"properties": {
    "identifier":               "1e4c59e1-r1rr-49bc-893d-990dsds8f9f5",
    "callStartTime":            "2022-08-14T06:18:27.010Z",
    "callDuration":             520,
    "callType":                 "P2P",
    "teamsThreadId":            "null",
    "participantId":            "null",
    "participantTenantId":      "02cbdb3c-155a-4b95-b829-6d56a45787ca",
    "participantStartTime":     "2022-08-14T06:18:27.010Z",
    "participantDuration":      "520",
    "participantEndReason":     "0",
    "endpointId":               "02cbdb3c-155a-4d98-b829-aaaaa61d44ea",
    "endpointType":             "VoIP",
    "sdkVersion":               "Redacted",
    "osVersion":                "Redacted"
}

以下是 PSTN 呼叫的呼叫摘要：

注意

无论是参与者的租户还是机器人的租户，P2P 或群组呼叫日志都会编辑 OS 和 SDK 版本。

"properties": {
    "identifier": "b1999c3e-bbbb-4650-9b23-9999bdabab47",
    "callStartTime": "2022-08-07T13:53:12Z",
    "callDuration": 1470,
    "callType": "Group",
    "teamsThreadId": "19:36ec5177126fff000aaa521670c804a3@thread.v2",
    "participantId": " b25cf111-73df-4e0a-a888-640000abe34d",
    "participantStartTime": "2022-08-07T13:56:45Z",
    "participantDuration": 960,
    "participantEndReason": "0",
    "endpointId": "8731d003-6c1e-4808-8159-effff000aaa2",
    "endpointType": "PSTN",
    "sdkVersion": "Redacted",
    "osVersion": "Redacted"
}

群组通话

群组呼叫的数据在三个呼叫摘要日志和六个呼叫诊断日志中生成。 以下是呼叫中所有日志的共享字段：

"time":                     "2021-07-05T06:30:06.402Z",
"resourceId":               "SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/ACS-TEST-RG/PROVIDERS/MICROSOFT.COMMUNICATION/COMMUNICATIONSERVICES/ACS-PROD-CCTS-TESTS",
"correlationId":            "bbbb1111-cc22-3333-44dd-555555eeeeee",

呼叫摘要日志

呼叫摘要日志共享操作和类别信息：

"operationName":            "CallSummary",
"operationVersion":         "1.0",
"category":                 "CallSummary",

以下是 VoIP 终结点 1 的呼叫摘要：

"properties": {
    "identifier":               "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-729f-ac00-343a0d00d975",
    "callStartTime":            "2021-07-05T06:16:40.240Z",
    "callDuration":             87,
    "callType":                 "Group",
    "teamsThreadId":            "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",
    "participantId":            "04cc26f5-a86d-481c-b9f9-7a40be4d6fba",
    "participantStartTime":     "2021-07-05T06:16:44.235Z",
    "participantDuration":      "82",
    "participantEndReason":     "0",
    "endpointId":               "5ebd55df-ffff-ffff-89e6-4f3f0453b1a6",
    "endpointType":             "VoIP",
    "sdkVersion":               "1.0.0.3",
    "osVersion":                "Darwin Kernel Version 18.7.0: Mon Nov 9 15:07:15 PST 2020; root:xnu-4903.272.3~3/RELEASE_ARM64_S5L8960X"
}

以下是 VoIP 终结点 3 的呼叫摘要：

"properties": {
    "identifier":               "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-57c6-ac00-343a0d00d972",
    "callStartTime":            "2021-07-05T06:16:40.240Z",
    "callDuration":             87,
    "callType":                 "Group",
    "teamsThreadId":            "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLTk2ZDUtYTZlM2I2ZjgxOTkw@thread.v2",
    "participantId":            "1a9cb3d1-7898-4063-b3d2-26c1630ecf03",
    "participantStartTime":     "2021-07-05T06:16:40.240Z",
    "participantDuration":      "87",
    "participantEndReason":     "0",
    "endpointId":               "5ebd55df-ffff-ffff-ab89-19ff584890b7",
    "endpointType":             "VoIP",
    "sdkVersion":               "1.0.0.3",
    "osVersion":                "Android 11.0; Manufacturer: Google; Product: redfin; Model: Pixel 5; Hardware: redfin"
}

以下是 VoIP 终结点 2 的呼叫摘要：

"properties": {
    "identifier":               "null",
    "callStartTime":            "2021-07-05T06:16:40.240Z",
    "callDuration":             87,
    "callType":                 "Group",
    "teamsThreadId":            "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",
    "participantId":            "515650f7-8204-4079-ac9d-d8f4bf07b04c",
    "participantStartTime":     "2021-07-05T06:17:10.447Z",
    "participantDuration":      "52",
    "participantEndReason":     "0",
    "endpointId":               "46387150-692a-47be-8c9d-1237efe6c48b",
    "endpointType":             "PSTN",
    "sdkVersion":               "null",
    "osVersion":                "null"
}

以下是跨租户呼叫摘要日志：

"properties": {
    "identifier":               "1e4c59e1-r1rr-49bc-893d-990dsds8f9f5",
    "callStartTime":            "2022-08-14T06:18:27.010Z",
    "callDuration":             912,
    "callType":                 "Group",
    "teamsThreadId":            "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",
    "participantId":            "aa1dd7da-5922-4bb1-a4fa-e350a111fd9c",
    "participantTenantId":      "02cbdb3c-155a-4b95-b829-6d56a45787ca",
    "participantStartTime":     "2022-08-14T06:18:27.010Z",
    "participantDuration":      "902",
    "participantEndReason":     "0",
    "endpointId":               "02cbdb3c-155a-4d98-b829-aaaaa61d44ea",
    "endpointType":             "VoIP",
    "sdkVersion":               "Redacted",
    "osVersion":                "Redacted"
}

以下是将机器人作为参与者的跨租户呼叫摘要日志：


"properties": {
    "identifier":             "b1902c3e-b9f7-4650-9b23-9999bdabab47",
    "callStartTime":          "2022-08-09T16:00:32Z",
    "callDuration":            1470,
    "callType":               "Group",
    "teamsThreadId":         "19:meeting_MmQwZDcwYTQtZ000HWE6NzI4LTg1YTAtNXXXXX99999ZZZZZ@thread.v2",
    "participantId":           "66e9d9a7-a434-4663-d91d-fb1ea73ff31e",
    "participantStartTime":    "2022-08-09T16:14:18Z",
    "participantDuration":      644,
    "participantEndReason":    "0",
    "endpointId":             "69680ec2-5ac0-4a3c-9574-eaaa77720b82",
    "endpointType":           "Bot",
    "sdkVersion":             "Redacted",
    "osVersion":              "Redacted"
}

常见问题解答

如何存储日志？

以下部分将对这一要求进行说明。

默认情况下，Azure 通信服务日志不会存储在 Azure 帐户中，因此你需要开始存储这些日志，以便“语音和视频见解”仪表板和通话诊断等工具正常工作。 要收集这些呼叫日志，需要启用将呼叫数据定向到 Log Analytics 工作区的诊断设置。

数据不会进行追溯性存储，因此仅在配置诊断设置后开始捕获呼叫日志。

按照在 Azure Monitor 中通过诊断设置启用日志为资源添加诊断设置。 建议最初收集所有日志。 了解 Azure Monitor 中的功能后，确定要保留哪些日志以及要保留多长时间。 添加诊断设置时，系统会提示你选择日志。 若要收集所有日志，请选择“allLogs”。

Azure Monitor 的 Log Analytics 中的数据量、保留期和使用情况通过现有的 Azure 数据计量计费。 出于成本考虑，建议根据需要监视数据使用情况和保留策略。 有关详细信息，请参阅控制成本。

如果你有多个 Azure 通信服务资源 ID，则必须为每个资源 ID 启用这些设置。

后续步骤