团队级Copilot使用情况指标

Copilot使用情况指标 API 不会发布单个预先聚合的团队报表。团队级指标通过加入 用户团队 报表（其中列出了每个用户的团队成员身份为给定日期）和 每用户使用情况指标 报告（其中包含当天每个用户 Copilot 的活动）来构造。按 team_id 对联接后的行进行聚合会生成团队级指标。

同一联接方案支持你所需的任何团队级别切片：按 (team, day)、按 (team, day, language)、按 (team, day, IDE)、通过滚动窗口等等。

正在获取报告

本指南中引用的两个报告分两步下载。首先，为所需日期调用 REST 终结点。终结点返回时间限制的签名 URL，可从中下载报表文件。然后下载这些 URL 指向的新行分隔 JSON （NDJSON）文件。用户-团队关系和按用户划分的记录包含在这些 NDJSON 文件中；REST 端点不会以内联方式返回它们。

报表	终结点
组织用户团队	`GET /orgs/{org}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD`
企业用户团队	`GET /enterprises/{enterprise}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD`
组织的每用户使用指标	`GET /orgs/{org}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD`
企业每位用户使用指标	`GET /enterprises/{enterprise}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD`

每个端点都返回如下形式的响应：

{
  "download_links": [
    "https://example.com/copilot-user-teams-report-1.ndjson"
  ],
  "report_day": "2026-05-07"
}

在链接有效期内，从每个 URL 下载文件，以获取该报表的各行数据。

有关完整的请求和响应架构、身份验证要求和相关终结点，请参阅用于 Copilot 使用情况指标的REST API终结点。有关如何定义单个使用情况指标字段的概述，请参阅 Copilot使用情况指标中提供的数据。

对于多日时间窗口，每天调用一次每日端点，并汇总每天的结果。请参阅下面的 “生成滚动窗口”团队报告。

涉及的报告

联接两个报告系列可以获得团队级别指标：团队成员资格用户团队报告和活动的每用户使用情况指标报告。

用户团队报告

这些报告在给定的某一天列出每个用户的团队成员身份。

报表	Scope	关键字段
`organization_user_teams_1_day`	当天的组织团队成员身份。仅包括组织中的团队。
`user_id`、`user_login`、`day`、`organization_id`、`team_id`、`slug`
`enterprise_user_teams_1_day`	当天的企业团队成员身份。包括企业团队和业务团队。
`user_id`、`user_login`、`day`、`enterprise_id`、`team_id`、`slug`

同一天属于多个团队的用户会显示为多行，每个 (user, team) 对都有一行。

重要

Copilot

影响：

在给定日期席位用户少于 5 个的团队不会出现在当天的用户团队报告中，即使其成员有 Copilot 活动也是如此。该活动仍显示在每用户使用情况指标报告中，但联接结果中不存在对应的团队行。

在多日窗口期间超过阈值的团队某些天会出现，其他天则缺席。只有团队高于阈值的天才会影响其总数。

如果将团队行汇总在一起，以便与企业或组织总数进行比较，则总和低于实体总数。不足之处是仅属于子阈值团队的用户的活动 - 他们在联接结果中没有团队行，因此任何团队聚合中均未表示他们的活动。

每位用户使用情况指标报告

这些报告包含给定一天每个用户 Copilot 的活动。

报表	Scope	关键字段
`organization_users_1_day`	每个 `(user_id, day, organization_id)` 一行，其中包含该组织中用户当天的 Copilot 活动。
`user_id`、、`day`、organization_id``enterprise_id活动计数器、细分数组
`users_1_day`	每个 `(user_id, day, enterprise_id)` 一行，表示该企业中用户当天的 Copilot 活动。
`user_id`、`day`、`enterprise_id`、活动计数器、细分数组

有关这些报表中可用的字段的完整列表，请参阅 Copilot使用情况指标中提供的数据。

警告

请勿将滚动 28 天的按用户划分报告（users_28_day、organization_users_28_day）与每日用户团队报告联接。用户-团队报告反映的是某一天的团队成员归属情况，因此，如果将 28 天的活动数据与单日成员归属快照进行联接，那么这整整 28 天的活动都会被归因到该用户在联接当日恰好所属的团队。每当窗口期间团队成员身份发生更改时，此错误将活动归咎于错误的团队。始终先将每日活动数据与每日用户团队数据关联起来，然后再按所需的时间窗口进行聚合。

实体级报表

实体级报表（enterprise_28_day、、organization_28_day、enterprise_1_day``organization_1_day）是整个企业或组织的预聚合总计。它们既不包含 user_id，也不包含 team_id，因此无法与用户团队报告关联以生成按团队划分的明细。当你需要企业或组织总计时，请直接使用它们；对于团队级别总计，请使用下面描述的每日用户团队 + 每日每用户指标联接。

示例

此最小端到端示例生成一天的组织团队指标。下面针对每个输入报告给出的示例 NDJSON 行，与您在从该报告的某个 download_links 下载的文件中看到的行类似（请参阅上文中的获取报告）。

两个用户在组织 Copilot 中在 2026-05-07 有 999 活动：

爱丽丝 （user_id=1001）当天属于两支球队： frontend （team_id=42）和 backend （team_id=43）。
鲍勃（user_id=1002）只属于 frontend （team_id=42）。

输入: `organization_user_teams_1_day`

{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "team_id": 42, "slug": "frontend"}
{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "team_id": 43, "slug": "backend"}
{"user_id": 1002, "user_login": "bob",   "day": "2026-05-07", "organization_id": "999", "team_id": 42, "slug": "frontend"}

Alice 会显示两次——她所属的每个团队各占一行。

输入: `organization_users_1_day`

{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "enterprise_id": "13213",
 "user_initiated_interaction_count": 50, "code_generation_activity_count": 40, "code_acceptance_activity_count": 12,
 "loc_suggested_to_add_sum": 200, "loc_added_sum": 88, "used_chat": true,  "used_agent": true,  ...}
{"user_id": 1002, "user_login": "bob",   "day": "2026-05-07", "organization_id": "999", "enterprise_id": "13213",
 "user_initiated_interaction_count": 30, "code_generation_activity_count": 25, "code_acceptance_activity_count": 7,
 "loc_suggested_to_add_sum": 80,  "loc_added_sum": 24, "used_chat": true,  "used_agent": false, ...}

每个 (user, day, organization) 一行。活动总数为当天所有界面的汇总值。

连接并聚合后的结果

基于 (user_id, day, organization_id) 对两个报表执行内联接，然后按 team_id 分组并聚合。下面的 active_users 列是聚合输出（COUNT(DISTINCT user_id)），而不是每个用户报表上的字段;其余数值列是匹配报表字段的总和。

team_id	数据域	活跃用户	code_acceptance_activity_count	loc_added_sum
42	frontend	2	19	112
43	后端	1	12	88

两个团队-日行，每个团队一行。该 frontend 行聚合 Alice 和 Bob 的活动。该 backend 行仅包含 Alice 的活动。

Alice 的活动对两个团队都做出了贡献。 12 和 88 来自 frontend 中的行计数，也来自 backend 中的行计数。这符合团队级指标的设计意图——每个团队都能看到其成员的活动情况——但如果将这两行团队数据再汇总为单个组织总计，就会对 Alice 进行重复计数。对于组织总数，无需用户-团队联接即可直接查询 organization_users_1_day。

如何构建团队级指标

对于任何团队层面的划分，同样适用这四个步骤。

选取报表对。
- 对于组织团队，请将organization_user_teams_1_day与organization_users_1_day配对。共享实体 ID 为 organization_id.
- 对于企业和业务团队，请将 enterprise_user_teams_1_day 与 users_1_day 搭配使用。共享实体 ID 为 enterprise_id.

          基于 ****`(user_id, day, entity_id)`。 这三个键必须匹配。 在团队方面，联接是一对多联接 - 多个团队中的用户与多个用户-团队行匹配。

按 day 筛选出你想要的那一天。这两个报表具有相同 day 的值。
按 team_id 分组（以及按团队的显示名称 slug 分组）并进行聚合。使用：
- COUNT(DISTINCT user_id) 用于统计独立用户数，例如活跃用户。
- ```
          卷计数器（例如 `SUM(...)`、`code_generation_activity_count` 和 `loc_added_sum`）的 `user_initiated_interaction_count`。
```

此联接是内部联接：仅当团队的至少一名成员在给定日期进行了活动时，该团队才会出现在这天的结果中。要列出当天没有活动的团队，请从用户-团队报告中进行左联接并将空计数器视为零。

按语言、IDE、功能或模型划分

各维度的细分位于每个用户行的数组字段（totals_by_ide、totals_by_language_feature、totals_by_language_model、totals_by_model_feature）中。要按维度进行分组，请展开联接中的相关数组，将维度列添加到分组中，然后聚合范围限定为该维度的每元素计数器。 language 和 ide 分别位于不同的数组中，因此团队级别的 (language × ide) 交叉表需要在应用程序中合并的两个查询。

生成滚动窗口团队报告

若要生成滚动窗口团队报告（例如，28 天汇总）：

在窗口中调用每天的每日终结点。
将每天的每位用户使用指标报告（organization_users_1_day 或 users_1_day）与同一天的用户团队报告（organization_user_teams_1_day 或 enterprise_user_teams_1_day）按 (user_id, day, entity_id) 进行关联。
筛选 day 到窗口，然后从分组中删除 day 。

容量计数器可跨天累加；请在该时间窗口内将其求和。非重复用户计数在整个窗口的联接行上必须计算为 COUNT(DISTINCT user_id) - 它们不能在每日计数中求和。

每天联接可确保每天的活动归属于用户当天所在的团队。如果没有它，在该时间窗口内发生的团队成员变更会悄无声息地将活动错误地归因给错误的团队。

限制和注意事项

多个团队中的用户为他们所属的每个团队做出贡献。 将各团队行数据汇总回组织或企业总计时务必小心——属于多个团队的用户会被重复计算。直接使用每用户报告（没有用户-团队联接）进行组织或企业总计。
低于阈值的团队未显示在用户团队报告中。 在某一天拥有少于 5 名已分配席位的 Copilot 用户的团队将被排除，因此其活动不会反映在团队级别结果中，不过这些活动仍会显示在按用户划分的报告中。
不同用户计数不能在几天内求和。 在多日时间窗口内汇总时，应基于整个时间窗口中的联接行来计算 COUNT(DISTINCT user_id)，而不是将每日计数相加。
已跟踪更多特征曲面。 容量计数器（code_generation_activity_count、code_acceptance_activity_count 和 loc_* 计数器）将汇总多个 Copilot 界面中的活动 - 内联 IDE 补全、聊天面板操作，以及 Copilot 代理编辑（适用于已接受行计数器）。有关每个计数器的表面覆盖详细信息，请参阅 Copilot使用情况指标中提供的数据。如果你之前从仅计算内联 IDE 补全的表面中使用了类似指标，则预计这些计数器中的值会更高，请重新设定基线，而不是在切换过程中进行比较。
利用新维度。 每个用户行都提供每 IDE、每功能、每 (language, feature)、每 (language, model) 以及每 (model, feature) 细分，从而能够获得以前的团队指标界面不支持的团队级别报告。

后续步骤

有关每用户使用情况指标报告的完整架构和字段参考，请参阅 Copilot使用情况指标中提供的数据。
有关使用情况指标端点的 JSON 负载示例，请参阅 Copilot使用情况指标的示例架构。
有关跨仪表板、API 和导出协调指标的指导，请参阅跨仪表板、API 和报表协调 Copilot 使用情况指标。

谁可以使用此功能？

在本文中