Métricas de uso de Copilot no nível da equipe

As Copilot APIs de métricas de uso não publicam um único relatório de equipe pré-agregado. As métricas no nível da equipe são construídas pela junção do relatório user-teams (que lista os vínculos de equipe de cada usuário em um determinado dia) com o relatório de métricas de uso por usuário (que contém a atividade de cada usuário Copilot nesse dia). Agrupar as linhas combinadas por team_id produz métricas no nível da equipe.

A mesma receita de junção oferece suporte a qualquer recorte no nível da equipe de que você precisar: por (team, day), por (team, day, language), por (team, day, IDE), em janelas móveis e assim por diante.

Obtendo os relatórios

Os dois relatórios referenciados neste guia são baixados em duas etapas. Primeiro, chame o endpoint REST do dia desejado. O endpoint retorna URLs assinadas com prazo de validade, por meio das quais é possível baixar os arquivos do relatório. Em seguida, baixe os arquivos JSON que essas URLs apontam. As linhas de equipe-usuário e as linhas por usuário estão nesses arquivos JSON; essas linhas não são retornadas diretamente na resposta pelo endpoint REST.

Relatório	Endpoint
Equipes de usuários da organização	GET /orgs/{org}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD
Equipes de usuários corporativas	GET /enterprises/{enterprise}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD
Métricas de uso por usuário da organização	GET /orgs/{org}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD
Métricas empresariais de uso por usuário	GET /enterprises/{enterprise}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD

Cada endpoint retorna uma resposta no formato:

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

Baixe o arquivo em cada URL dentro do período de validade do link para recuperar as linhas do relatório.

Para obter esquemas de solicitação e resposta completos, requisitos de autenticação e pontos de extremidade relacionados, consulte Endpoints da API REST para métricas de uso do Copilot. Para obter uma visão geral de como os campos de métrica de uso individual são definidos, consulte Dados disponíveis nas métricas de uso do Copilot.

Para um período de vários dias, chame os endpoints diários uma vez por dia e agregue os resultados diários. Veja Criando relatórios de equipe em janela móvel abaixo.

Relatórios envolvidos

As métricas de nível de equipe vêm da junção de duas famílias de relatórios: relatórios de equipes de usuários para associação de equipe e relatórios de métricas de uso por usuário para atividade.

Relatórios de equipes de usuários

Esses relatórios listam as associações de equipe de cada usuário em um determinado dia.

Relatório	Scope	Campos de chave
organization_user_teams_1_day	Participação na equipe da organização do dia. Inclui apenas equipes da organização.
user_id, user_login, day, organization_id, , team_id``slug
enterprise_user_teams_1_day	Assinatura da equipe corporativa por um dia. Inclui equipes empresariais e equipes de negócios.
user_id, user_login, day, enterprise_id, , team_id``slug

Um usuário que pertence a várias equipes no mesmo dia aparece em várias linhas, uma linha por (user, team) par.

Relatórios de métricas de uso por usuário

Esses relatórios contêm a atividade de Copilot cada usuário para um determinado dia.

Relatório	Scope	Campos de chave
organization_users_1_day	Uma linha por (user_id, day, organization_id) com a atividade do Copilot usuário dentro dessa organização para o dia.
user_id, day, organization_id, enterprise_idcontadores de atividade, matrizes de divisão
users_1_day	Uma linha por (user_id, day, enterprise_id) com a atividade do usuário Copilot nessa empresa no dia.
user_id, day, enterprise_idcontadores de atividade, matrizes de divisão

Para obter a lista completa de campos disponíveis nesses relatórios, consulte Dados disponíveis nas métricas de uso do Copilot.

Relatórios de nível de entidade

Os relatórios de nível de entidade (enterprise_28_day, , organization_28_day, enterprise_1_day) organization_1_daysão totais pré-agregados para toda a empresa ou organização. Eles não carregam user_id ou team_id e não podem ser combinados com o relatório de equipes de usuários para produzir detalhamentos por equipe. Use-os diretamente quando quiser totais da empresa ou da organização; para totais no nível da equipe, use a junção entre daily user-teams e daily per-user-metrics descrita abaixo.

Example

Este exemplo mínimo de ponta a ponta produz um dia de métricas de equipe da organização. O JSON mostrado abaixo para cada relatório de entrada é um exemplo das linhas que você encontraria no arquivo baixado de um dos relatórios download_links (consulte Buscar os relatórios acima).

Dois usuários têm Copilot atividade em 2026-05-07 na organização 999:

• Alice (user_id=1001) pertence a duas equipes naquele dia: frontend (team_id=42) e backend (team_id=43).
• Bob (user_id=1002) pertence apenas a frontend (team_id=42)

Entrada: 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 aparece duas vezes — uma linha para cada equipe da qual ela faz parte.

Entrada: 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, ...}

Uma linha por (user, day, organization). Os totais de atividade correspondem ao dia, somados em todas as superfícies.

Resultado agregado e unido

Faça uma junção interna entre os dois relatórios em (user_id, day, organization_id), depois agrupe por team_id e agregue. A active_users coluna abaixo é uma saída de agregação (COUNT(DISTINCT user_id)), não um campo no relatório por usuário; as colunas numéricas restantes são somas dos campos de relatório correspondentes.

team_id	slug	usuarios_ativos	codigo_aceitacao_contagem_atividade	loc_added_sum
42	frontend	2	19	112
43	back-end	1	12	88

Duas linhas de dia de equipe, uma por equipe. A frontend linha agrega a atividade de Alice e Bob. A backend linha contém apenas a atividade de Alice.

A atividade de Alice contribui para ambas as equipes. Os números 12 e 88 da contagem de linhas dela em frontend e novamente em backend. Isso corresponde à intenção das métricas por equipe — cada equipe vê a atividade de seus membros —, mas somar novamente as duas linhas da equipe em um único total da organização faz com que Alice seja contada em dobro. Para os totais da organização, consulte organization_users_1_day diretamente, sem fazer join com user-teams.

Como construir métricas de nível de equipe

Para qualquer fatia de nível de equipe, as mesmas quatro etapas se aplicam.

1. Escolha o par de relatórios.

   • Para equipes da organização, combine organization_user_teams_1_day com organization_users_1_day. A ID da entidade compartilhada é organization_id.
   • Para equipes empresariais e de negócios, emparelhe enterprise_user_teams_1_day com users_1_day. A ID da entidade compartilhada é enterprise_id.

2. Faça uma junção interna entre os dois relatórios com base em (user_id, day, entity_id). Todas as três chaves devem corresponder. A junção é de um para muitos do lado da equipe — um usuário que pertence a várias equipes corresponde a várias linhas da tabela user-teams.

3. Filtrar por day para o dia que você quiser. Ambos os relatórios têm o mesmo day valor.

4. Agrupar por team_id (e slug para o nome de exibição da equipe) e agregue. Uso:

   • COUNT(DISTINCT user_id) para contagens de usuários distintos, como usuários ativos.
   • SUM(...) para contadores de volume, como code_generation_activity_count, loc_added_sume user_initiated_interaction_count.

A junção é uma junção interna: uma equipe aparece no resultado de um determinado dia somente se pelo menos um de seus membros tiver atividade naquele dia. Para listar as equipes que não tiveram atividade no dia, faça um LEFT JOIN a partir do relatório de equipes de usuários e trate os contadores nulos como zero.

Corte por linguagem, IDE, recurso ou modelo

Os detalhamentos por dimensão ficam em campos de array em cada linha de usuário (totals_by_ide, totals_by_language_feature, totals_by_language_model, totals_by_model_feature). Para agrupar por uma dimensão, expanda a matriz relevante como parte da junção, adicione as colunas de dimensão ao agrupamento e agrupe os contadores por elemento com escopo para essa dimensão. language e ide estão em arrays separados, portanto uma tabela cruzada de (language × ide) no nível da equipe exige duas consultas combinadas no seu aplicativo.

Criando relatórios da equipe em janela deslizante

Para produzir um relatório de equipe com janela móvel (por exemplo, uma consolidação de 28 dias):

1. Faça chamadas aos endpoints diários para cada dia na janela de tempo.
2. Combine o relatório diário de métricas de uso por usuário (organization_users_1_day ou users_1_day) com o relatório de equipes dos usuários do mesmo dia (organization_user_teams_1_day ou enterprise_user_teams_1_day) com base em (user_id, day, entity_id).
3. Filtre day na janela e remova day do agrupamento.

Os contadores de volume são aditivos entre os dias; some-os ao longo da janela. As contagens de usuários distintos devem ser avaliadas como COUNT(DISTINCT user_id) sobre as linhas combinadas da janela completa — elas não podem ser somadas entre contagens diárias.

A junção diária é o que garante que a atividade de cada dia seja atribuída às equipes das quais o usuário fazia parte naquele dia. Sem isso, alterações no pertencimento à equipe durante o período atribuem incorretamente, sem aviso, a atividade às equipes erradas.

Limitações e ressalvas

• Os usuários em várias equipes contribuem para cada equipe à qual pertencem. Tenha cuidado ao agregar novamente linhas por equipe a um total da organização ou da empresa — usuários que pertencem a várias equipes serão contados mais de uma vez. Use o relatório por usuário diretamente (sem o ingresso no user-teams) para totais corporativos ou de organização.
• As equipes abaixo do limite estão ausentes do relatório de equipes de usuários. Equipes com menos de 5 usuários sentados Copilot em um determinado dia são excluídas, portanto, sua atividade não é representada em resultados de nível de equipe, mesmo que a atividade ainda esteja no relatório por usuário.
• Contagens de usuários distintos não podem ser resumidas ao longo dos dias. Ao rolar em uma janela de vários dias, avalie COUNT(DISTINCT user_id) as linhas unidas para toda a janela em vez de resumir contagens diárias.
• Mais áreas de funcionalidades são rastreadas. Os contadores de volume (code_generation_activity_count, code_acceptance_activity_count e os contadores loc_*) agregam atividades em várias interfaces Copilot — complementações inline na IDE, ações no painel de chat e, no caso dos contadores de linhas aceitas, edições agente do Copilot. Para obter detalhes de cobertura de superfície por contador, consulte Dados disponíveis nas métricas de uso do Copilot. Se você já usava métricas semelhantes de uma origem que contava apenas as complementações inline do IDE, espere valores mais altos nesses contadores e redefina a linha de base em vez de comparar os dados antes e depois da transição.
• Aproveite as novas dimensões. Detalhamentos por IDE, por recurso, por (language, feature), por (language, model) e por (model, feature) estão disponíveis em cada linha de usuário, possibilitando relatórios no nível da equipe que as visualizações anteriores de métricas de equipe não suportavam.

Próximas Etapas 

• Para obter o esquema completo e a referência de campo para o relatório de métricas de uso por usuário, consulte Dados disponíveis nas métricas de uso do Copilot.
• Por exemplo, para ver exemplos de payloads JSON dos endpoints de métricas de uso, consulte Esquema de exemplo para métricas de uso de Copilot.
• Para obter diretrizes sobre como reconciliar métricas no painel, APIs e exportações, consulte Reconciliando métricas de uso do Copilot entre dashboards, APIs e relatórios.