# チーム レベルのCopilot使用状況メトリック

毎日のユーザー チーム レポートと毎日のユーザーごとの使用状況メトリック レポートを結合して、チーム レベルの GitHub Copilot 使用状況メトリックを構築します。

Copilot使用状況メトリック API では、事前に集計された 1 つのチーム レポートは発行されません。 チーム レベルのメトリックは、(特定の日の各ユーザーのチーム メンバーシップを一覧表示する) **ユーザー チーム** レポートと **ユーザーごとの使用状況メトリック** レポート (その日の各ユーザーの Copilot アクティビティを含む) を結合することによって構築されます。 結合された行を `team_id` で集計すると、チーム レベルのメトリックが生成されます。

この結合レシピは、必要なあらゆるチームレベルの切り出しに対応しています。たとえば、`(team, day)` ごと、`(team, day, language)` ごと、`(team, day, IDE)` ごと、ローリング ウィンドウ単位などです。

> \[!NOTE]
> チーム レベルの導入の UI ベースのビューのみが必要な場合、影響ダッシュボードのユーザー チーム マッピングは、この記事で説明する結合を構築しなくても、チーム レベルの導入コーホート データをネイティブに表示します。 「[Copilot影響ダッシュボードの表示](/ja/copilot/how-tos/administer-copilot/view-impact-dashboard)」を参照してください。 カスタム BI レポートや、導入コーホートを超えたチーム レベルのメトリックなど、チームごとの生の NDJSON データが必要な場合は、以下で説明する手動参加を使用します。

## レポートを取得しています

このガイドで参照されている 2 つのレポートは、2 つの手順でダウンロードされます。 最初に、必要な日に 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`      |

各エンドポイントは、次の形式の応答を返します。

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

リンクの有効期限ウィンドウ内の各 URL にファイルをダウンロードして、そのレポートの行を取得します。

完全な要求と応答のスキーマ、認証要件、および関連するエンドポイントについては、 [Copilot使用状況メトリックの REST API エンドポイント](/ja/rest/copilot/copilot-usage-metrics) を参照してください。 個々の使用状況メトリック フィールドの定義方法の概要については、 [Copilot使用状況メトリックで使用可能なデータ](/ja/copilot/reference/copilot-usage-metrics/copilot-usage-metrics) を参照してください。

複数日の期間の場合は、1 日に 1 回毎日のエンドポイントを呼び出し、毎日の結果を集計します。 以下の[ローリングウィンドウ チーム レポートの作成](#building-rolling-window-team-reports)を参照してください。

## 関連するレポート

チーム レベルのメトリックは、チーム メンバーシップのユーザー チーム レポートと、アクティビティのユーザーごとの使用状況メトリック レポートという 2 つのレポート ファミリに参加した場合に生じます。

### ユーザー チーム レポート

これらのレポートには、特定の日に各ユーザーのチーム メンバーシップが一覧表示されます。

| レポート                                                                 | 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)` ペアごとに 1 行) に表示されます。

> \[!IMPORTANT]
> **ユーザーが座っている Copilot が 5 人未満のチームは、ユーザー チーム レポートから除外されます。**
>
> 影響：
>
> * 特定の日に座っているユーザーが 5 人未満のチームは、メンバーがアクティビティを Copilot している場合でも、その日のユーザー チーム レポートには表示されません。 アクティビティはユーザーごとの使用状況メトリック レポートに残りますが、結合結果にチーム行は存在しません。
> * 複数日の期間にしきい値を超えるチームは、一部の日に存在し、他のチームには存在しません。 チームがしきい値を超えている日のみが、その合計に影響します。
> * チームの行を合計して企業または組織の合計と比較すると、合計はエンティティの合計よりも低くなります。 不足は、サブしきい値のチームにのみ属するユーザーからのアクティビティであり、参加結果にチーム行がないため、アクティビティはどのチーム集計にも表されません。

### ユーザーごとの使用状況メトリック レポート

これらのレポートには、特定の日の各ユーザーの Copilot アクティビティが含まれます。

| レポート                                                                             | Scope                                                                   | 主要なフィールド |
| :------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | :------- |
| `organization_users_1_day`                                                       | その日の組織内のユーザーの`(user_id, day, organization_id)`アクティビティを含むCopilotごとに 1 行。 |          |
| `user_id`、 `day`、 `organization_id`、 `enterprise_id`、アクティビティ カウンター、ブレークダウン配列     |                                                                         |          |
| `users_1_day`                                                                    |                                                                         |          |
| `(user_id, day, enterprise_id)`ごとに 1 行、その日のエンタープライズ内でユーザーのCopilotアクティビティが表示されます。 |                                                                         |          |
| `user_id`、 `day`、 `enterprise_id`、アクティビティ カウンター、ブレークダウン配列                        |                                                                         |          |

これらのレポートで使用できるフィールドの完全な一覧については、 [Copilot使用状況メトリックで使用可能なデータ](/ja/copilot/reference/copilot-usage-metrics/copilot-usage-metrics) を参照してください。

> \[!WARNING]
> ローリング 28 日間のユーザーごとのレポート (`users_28_day`、`organization_users_28_day`) を日次のユーザー チーム レポートと結合しないでください。 ユーザー チーム レポートには 1 日のチーム メンバーシップが反映されるため、1 日のメンバーシップ スナップショットに対して 28 日間のアクティビティに参加すると、ユーザーが参加日に属するチームに対する 28 日間のアクティビティの完全な属性が設定されます。 この誤った属性により、ウィンドウの間にチーム メンバーシップが変更されるたびに、アクティビティが間違ったチームに与えられます。 必ず日々の活動を日々のユーザーチームごとに集計し、その後、希望する期間ごとに集計してください。

### エンティティ レベルのレポート

エンティティ レベルのレポート (`enterprise_28_day`、 `organization_28_day`、 `enterprise_1_day`、 `organization_1_day`) は、企業全体または組織全体の集計済みの合計です。
`user_id`や`team_id`は含まれません。また、ユーザー チーム レポートに参加してチームごとの内訳を生成することはできません。 エンタープライズまたは組織の合計が必要な場合は、それらを直接使用します。チーム レベルの合計では、以下で説明する日単位のユーザー チーム + 毎日のユーザーごとのメトリック参加を使用します。

## 例

この最小限のエンドツーエンドの例では、1 日分の組織チームメトリックが生成されます。 各入力レポートの下のサンプル NDJSON 行は、そのレポートのいずれかの `download_links` からダウンロードしたファイルで見つかる行と似ています (上記の [レポートのフェッチを](#fetching-the-reports) 参照)。

2 人のユーザーは、組織のCopilotで 2026-05-07 に`999`アクティビティを行っています。

* **Alice** (`user_id=1001`) は、 `frontend` (`team_id=42`) と `backend` (`team_id=43`) の 2 つのチームに属しています。
* **Bob** (`user_id=1002`) は、 `frontend` (`team_id=42`) にのみ属しています。

### 入力: `organization_user_teams_1_day`

```json
{"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 は 2 回表示されます。所属するチームごとに 1 行ずつ表示されます。

### 入力: `organization_users_1_day`

```json
{"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)`ごとに 1 行。 アクティビティの合計は、その日のすべてのサーフェスにまたがる合計値です。

### 結合および集計された結果

`(user_id, day, organization_id)`に関する 2 つのレポートを内部結合し、`team_id`グループ化して集計します。 次の `active_users` 列は集計出力 (`COUNT(DISTINCT user_id)`) であり、ユーザーごとのレポートのフィールドではありません。残りの数値列は、一致するレポート フィールドの合計です。

| team\_id | スラッグ     | アクティブユーザー | コード承認アクティビティ件数 | loc\_added\_sum |
| :------- | :------- | :-------- | :------------- | :-------------- |
| 42       | frontend | 2         | 19             | 112             |
| 43       | バックエンド   | 1         | 12             | 88              |

チームごとの日次報告を 2 回、各チーム 1 回ずつ。
`frontend`行は、Alice と Bob のアクティビティの両方を集計します。
`backend`行には Alice のアクティビティのみが含まれます。

Aliceの活動は**両方**のチームに貢献しています。 彼女の列にある 12 と 88 は、`frontend` でカウントされ、さらに `backend` でもカウントされます。 これはチームレベルのメトリックの意図に合致しています。つまり、各チームにはそのメンバーのアクティビティが表示されますが、2 つのチーム行を合算して組織全体の単一の合計値に戻すと、Alice が二重にカウントされてしまいます。 組織の合計については、ユーザー チームの参加なしで直接 `organization_users_1_day` クエリを実行します。

## チーム レベルのメトリックを構築する方法

チーム レベルのスライスには、同じ 4 つの手順が適用されます。

1. **レポートペアを選択します。**

   * 組織チームの場合は、`organization_user_teams_1_day`と`organization_users_1_day`をペアにします。 共有エンティティ ID が `organization_id`。
   * エンタープライズ チームとビジネス チームの場合は、 `enterprise_user_teams_1_day` を `users_1_day`と組み合わせて使用します。 共有エンティティ ID が `enterprise_id`。

2. \*\*
   \*\*。 3 つのキーはすべて一致する必要があります。 チーム側では 1 対多の関係になります。つまり、複数のチームに所属する 1 人のユーザーは、複数の user-teams の行に対応します。

3. \*\*
   `day`で\*\*希望の日に絞り込みます。 どちらのレポートも同じ `day` 値を保持します。

4. \*\*
   `team_id`でグループ化し\*\*（チームの表示名には`slug`を使用して）集計します。 以下を使用してください。

   * `COUNT(DISTINCT user_id)` アクティブ ユーザーなどの個別のユーザー数の場合。
   * `SUM(...)`
     `code_generation_activity_count`、`loc_added_sum`、`user_initiated_interaction_count`などのボリューム カウンターの場合。

結合は内部結合です。チームは、その日に少なくとも 1 人のメンバーがアクティビティを行った場合にのみ、特定の日の結果に表示されます。 その日に活動がなかったチームを一覧表示するには、user-teams レポートと LEFT JOIN を行い、NULL のカウンターを 0 として扱います。

### 言語、IDE、機能、またはモデルによる切り取り

ディメンションごとの内訳は、各ユーザーの行にある配列フィールド（`totals_by_ide`、`totals_by_language_feature`、`totals_by_language_model`、`totals_by_model_feature`）に格納されています。 ディメンションでグループ化するには、結合の一部として関連する配列を展開し、ディメンション列をグループ化に追加し、そのディメンションにスコープを設定した要素ごとのカウンターを集計します。
`language`
`ide`は別々の配列に格納されるため、チーム レベルの`(language × ide)`クロスタブでは、アプリケーションで 2 つのクエリが結合されます。

### ローリング ウィンドウ チーム レポートの作成

ローリング ウィンドウ のチーム レポート (28 日間のロールアップなど) を生成するには:

1. ウィンドウ内の各日の毎日のエンドポイントを呼び出します。
2. `organization_users_1_day`の同じ日のユーザー チーム レポート (`users_1_day`または`organization_user_teams_1_day`) を使用して、毎日のユーザーごとの使用状況メトリック レポート (`enterprise_user_teams_1_day`または`(user_id, day, entity_id)`) に参加します。
3. ウィンドウへの `day` をフィルター処理し、グループ化から `day` をドロップします。

出来高カウンターは日ごとに累積されるため、指定した期間で合計されます。 個別ユーザー数は、完全なウィンドウの結合された行に対して `COUNT(DISTINCT user_id)` として評価する必要があります。日単位のカウントで合計することはできません。

日次の結合によって、各日のアクティビティは、ユーザーが **その日** 所属していたチームに確実に紐付けられます。 これを指定しないと、その期間中にチームの所属が変更された場合、アクティビティが誤ったチームに気付かれないまま誤って関連付けられます。

## 制限事項と注意事項

* **複数のチームのユーザーは、所属する各チームに貢献します。** チーム別の行を組織全体またはエンタープライズ全体の合計に合算する際は注意してください。複数のチームに所属するユーザーは、複数回カウントされます。 組織または企業の合計には、ユーザーごとのレポートを直接 (ユーザー チーム参加なしで) 使用します。
* **しきい値未満のチームは、ユーザーチーム レポートに含まれません。** 特定の日に座っている Copilot ユーザーが 5 人未満のチームは除外されるため、アクティビティがユーザーごとのレポートに残っている場合でも、そのアクティビティはチーム レベルの結果には表示されません。
* **個別ユーザー数は、日数をまたいで合計することはできません。** 複数日のウィンドウにロールアップするときは、1 日のカウントを合計するのではなく、ウィンドウ全体の結合された行に対して `COUNT(DISTINCT user_id)` を評価します。
* **より多くの特徴サーフェスが追跡されます。** ボリューム カウンター (`code_generation_activity_count`、 `code_acceptance_activity_count`、および `loc_*` カウンター) は、複数の Copilot サーフェス (インライン IDE 入力候補、チャット パネル アクション、および (承認済み行カウンターの場合) Copilot agent 編集) にわたるアクティビティを集計します。 カウンターごとのサーフェス カバレッジの詳細については、 [AUTOTITLE を](/ja/copilot/reference/copilot-usage-metrics/copilot-usage-metrics)参照してください。 これまで、インライン IDE 補完のみを集計対象としていた指標を利用していた場合は、これらのカウンターの値が高くなることを想定し、切り替え前後の差分比較を行うのではなく、基準値を再設定してください。
* **新しいディメンションを利用します。** IDEごと、機能ごと、`(language, feature)`ごと、`(language, model)`ごと、および`(model, feature)`ごとの内訳を各ユーザー行で確認できるため、従来のチーム指標画面ではサポートされていなかったチームレベルのレポートが可能になります。

## 次のステップ

* ユーザーごとの使用状況メトリック レポートのスキーマとフィールドの完全なリファレンスについては、 [Copilot使用状況メトリックで使用可能なデータ](/ja/copilot/reference/copilot-usage-metrics/copilot-usage-metrics) を参照してください。
* 使用状況メトリック エンドポイントからの JSON ペイロードの例については、 [Copilot使用状況メトリックのスキーマの例](/ja/copilot/reference/copilot-usage-metrics/example-schema) を参照してください。
* ダッシュボード、API、およびエクスポート全体のメトリックの調整に関するガイダンスについては、 [ダッシュボード、API、レポート全体での Copilot の使用状況メトリックの調整](/ja/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics) を参照してください。