Analysieren der Nutzung im Laufe der Zeit mit der Copilot-Metrik-API

Einführung

Du kannst die REST-API-Endpunkte für Copilot-Metriken verwenden, um Trends anzuzeigen, mit denen Benutzer GitHub Copilot übernehmen. Während eines Rollouts von GitHub Copilot ist es hilfreich, diese Trends anzuzeigen, um zu überprüfen, ob Personen ihre zugewiesenen Lizenzen verwenden, um anzuzeigen, welche Features von Personen verwendet werden, und um die Auswirkungen des Aktivierungsplans deines Unternehmens auf Entwickler nachzuvollziehen.

Die API umfasst:

Daten für die letzten 28 Tage
Anzahl aktiver und beteiligter Benutzer
Aufschlüsselungen nach Sprache und IDE
Option zum Anzeigen von Metriken für ein Unternehmen, eine Organisation oder ein Team

Wenn du derzeit die REST-API-Endpunkte für Metriken zur GitHub Copilot-Nutzung verwendest, wird es empfohlen, schnellstmöglich zur REST-API-Endpunkte für Copilot-Metriken zu migrieren.

In diesem Leitfaden wird veranschaulicht, wie du die API abfragst, Daten speicherst und einen Trend für Änderungen an der Anzahl der Benutzer pro Woche analysierst. Die Beispiele in diesem Leitfaden verwenden den Endpunkt für eine Organisation, du kannst jedoch die Beispiele an deine Anforderungen anpassen.

Informationen zur Verfügbarkeit von Endpunkten

Endpunkte sind für ein Unternehmen, eine Organisation, ein Organisationsteam oder ein Unternehmensteam zum Abrufen von Daten verfügbar.

Wenn du als Teil einer regulären Organisation oder eines regulären Unternehmens über ein GitHub Copilot Business- oder GitHub Copilot Enterprise-Abonnement verfügst, kannst du die Endpunkte für ein Unternehmen, eine Organisation oder ein Organisationsteam verwenden. Du hast keinen Zugriff auf Unternehmensteams, es sei denn, du hast dich für eine Vorschauversion registriert.
Wenn du für GitHub Copilot Business ein dediziertes Unternehmen verwendest – ein Unternehmenskonto, mit dem keine Organisationen erstellt werden können –, kannst du die Endpunkte für ein Unternehmen oder ein Unternehmensteam verwenden.

Voraussetzungen

Die Richtlinie für den Zugriff auf die Copilot-Metrik-API muss für dein Unternehmen oder deine Organisation aktiviert sein. Weitere Informationen findest du unter Verwalten von Richtlinien für Copilot in Ihrer Organisation oder Verwalten von Richtlinien und Features für Copilot in Ihrem Unternehmen.
Die Organisation, das Unternehmen oder das Team, das du abfragst, muss über ausreichend aktive Copilot-Benutzer verfügen. Die API gibt nur Ergebnisse für ein bestimmtes Tag zurück, wenn für dieses Tag mindestens fünf Mitglieder mit aktiven Copilot-Lizenzen vorhanden sind.
In diesem Beispiel wird ein JavaScript-Skript zum Abfragen und Analysieren der Daten erstellt. Um dieses Skript lokal auszuführen, musst du Node.js installieren und anschließend mit npm install -g octokit das Octokit.js-SDK- installieren.

1. Erstellen eines personal access token

Zum Abrufen von Metriken für eine Organisation wird beispielsweise ein personal access token (classic) mit dem Bereich manage_billing:copilot erstellt. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

Wenn du einen anderen Endpunkt verwendest, benötigst du möglicherweise unterschiedliche Bereiche. Weitere Informationen findest du unter REST-API-Endpunkte für Copilot-Metriken.

2. Herstellen einer Verbindung mit der API

Die API wird aus einem Skript aufgerufen, und die Antwort wird als Variable gespeichert. Anschließend können die Daten extern gespeichert und Trends in den Daten analysiert werden.

Im folgenden Beispiel wird der Octokit-Client für JavaScript verwendet. Du kannst weitere Methoden wie cURL oder die GitHub CLI verwenden, um die API aufzurufen.

Beispiel

In diesem Beispiel:

Ersetze YOUR_TOKEN durch dein personal access token.
Ersetze YOUR_ORG durch den Namen deiner Organisation wie octo-org.

JavaScript

// Import Octokit
import { Octokit } from "octokit";

// Set your token and organization
const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});
const org = 'YOUR_ORG';

// Set other variables if required for the endpoint you're using
/*
const team = 'YOUR_TEAM';
const enterprise = 'YOUR_ENTERPRISE';
const entTeam = 'YOUR_ENTERPRISE_TEAM';
*/

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  console.log(copilotUsage);
  }

// Call the function
orgMetrics();

import { Octokit } from "octokit";

Import Octokit

const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});
const org = 'YOUR_ORG';

Set your token and organization

/*
const team = 'YOUR_TEAM';
const enterprise = 'YOUR_ENTERPRISE';
const entTeam = 'YOUR_ENTERPRISE_TEAM';
*/

Set other variables if required for the endpoint you're using

async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });
  const copilotUsage = resp.data;
  console.log(copilotUsage);
  }

Call the API

orgMetrics();

Call the function

// Import Octokit
import { Octokit } from "octokit";

// Set your token and organization
const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});
const org = 'YOUR_ORG';

// Set other variables if required for the endpoint you're using
/*
const team = 'YOUR_TEAM';
const enterprise = 'YOUR_ENTERPRISE';
const entTeam = 'YOUR_ENTERPRISE_TEAM';
*/

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  console.log(copilotUsage);
  }

// Call the function
orgMetrics();

Lokales Ausführen des Skripts

Um das Skript lokal zu testen, speichere die Datei als copilot.mjs, und führe anschließend node copilot.mjs aus.

Important

Der Dateityp .mjs ist wichtig. Die import { Octokit }-Anweisung funktioniert möglicherweise nicht mit einer regulären .js-Datei.

In deinem Terminal sollte die Ausgabe mit einem JSON-Array wie dem folgenden angezeigt werden.

[
  {
    date: '2024-11-07',
    copilot_ide_chat: { editors: [Array], total_engaged_users: 14 },
    total_active_users: 28,
    copilot_dotcom_chat: { models: [Array], total_engaged_users: 4 },
    total_engaged_users: 28,
    copilot_dotcom_pull_requests: { total_engaged_users: 0 },
    copilot_ide_code_completions: { editors: [Array], total_engaged_users: 22 }
  },
...

3. Speichern der Daten

Um Trends über mehr als 28 Tage zu analysieren, musst du die folgenden Schritte ausführen:

Ruf die API täglich mithilfe eines Cronjobs oder eines geplanten GitHub Actions-Workflows auf.
Speichere Daten lokal oder mit einem Datenbankdienst wie MySQL.
Frage die Daten ab, um Trends im Laufe der Zeit zu identifizieren.

Beispiel

In diesem Beispiel werden die Daten in einer lokalen .json-Datei gespeichert. Dazu werden einige Module zum Arbeiten mit Dateien importiert und die orgMetrics-Funktion zum Speichern der Antwortdaten aktualisiert.

Die Funktion speichert neue Daten, die täglich zurückgegeben werden, ohne alte Daten in der Datei zu überschreiben.

Neue Schritte werden fett annotiert.

JavaScript

// Import Octokit
import { Octokit } from "octokit";

// **Import modules for working with files**
import path from 'path';
import fs from 'fs';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

// **Declare variables for working with files**
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Set your token and organization
const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});

const org = 'YOUR_ORG';

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  // **Define the path to the local file where data will be stored**
  const dataFilePath = path.join(__dirname, 'copilotMetricsData.json');

  // **Read existing data from the file, if it exists**
  let existingData = [];
  if (fs.existsSync(dataFilePath)) {
    const fileContent = fs.readFileSync(dataFilePath, 'utf8');
    existingData = JSON.parse(fileContent);
  }

  // **Filter out the new data that is not already in the existing data**
  const newData = copilotUsage.filter(entry => !existingData.some(existingEntry => existingEntry.date === entry.date));

  // **Append new data to the existing data**
  if (newData.length > 0) {
    existingData = existingData.concat(newData);

    // **Save the updated data back to the file**
    fs.writeFileSync(dataFilePath, JSON.stringify(existingData, null, 2));
    console.log(`Saved ${newData.length} new entries.`);
  } else {
    console.log('No new data to save.');
  }
}

// Call the function
orgMetrics();

import { Octokit } from "octokit";

Import Octokit

import path from 'path';
import fs from 'fs';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

Import modules for working with files

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Declare variables for working with files

const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});
const org = 'YOUR_ORG';

Set your token and organization

async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });
  const copilotUsage = resp.data;

Call the API

  const dataFilePath = path.join(__dirname, 'copilotMetricsData.json');

Define the path to the local file where data will be stored

  let existingData = [];
  if (fs.existsSync(dataFilePath)) {
    const fileContent = fs.readFileSync(dataFilePath, 'utf8');
    existingData = JSON.parse(fileContent);
  }

Read existing data from the file, if it exists

  const newData = copilotUsage.filter(entry => !existingData.some(existingEntry => existingEntry.date === entry.date));

Filter out the new data that is not already in the existing data

  if (newData.length > 0) {
    existingData = existingData.concat(newData);

Append new data to the existing data

    fs.writeFileSync(dataFilePath, JSON.stringify(existingData, null, 2));
    console.log(`Saved ${newData.length} new entries.`);
  } else {
    console.log('No new data to save.');
  }
}

Save the updated data back to the file

orgMetrics();

Call the function

// Import Octokit
import { Octokit } from "octokit";

// **Import modules for working with files**
import path from 'path';
import fs from 'fs';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

// **Declare variables for working with files**
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Set your token and organization
const octokit = new Octokit({
  auth: 'YOUR_TOKEN'
});

const org = 'YOUR_ORG';

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  // **Define the path to the local file where data will be stored**
  const dataFilePath = path.join(__dirname, 'copilotMetricsData.json');

  // **Read existing data from the file, if it exists**
  let existingData = [];
  if (fs.existsSync(dataFilePath)) {
    const fileContent = fs.readFileSync(dataFilePath, 'utf8');
    existingData = JSON.parse(fileContent);
  }

  // **Filter out the new data that is not already in the existing data**
  const newData = copilotUsage.filter(entry => !existingData.some(existingEntry => existingEntry.date === entry.date));

  // **Append new data to the existing data**
  if (newData.length > 0) {
    existingData = existingData.concat(newData);

    // **Save the updated data back to the file**
    fs.writeFileSync(dataFilePath, JSON.stringify(existingData, null, 2));
    console.log(`Saved ${newData.length} new entries.`);
  } else {
    console.log('No new data to save.');
  }
}

// Call the function
orgMetrics();

Lokales Ausführen des Skripts

Nachdem du das Skript mit node copilot.mjs ausgeführt hast, sollte sich in deinem Verzeichnis eine neue Datei mit dem Namen copilotMetricsData.json befinden. Die Datei sollte Daten aus der API-Antwort enthalten.

Wenn du das Skript morgen erneut ausführst, sollte es nur Daten für einen neuen Tag in der Datei speichern.

4. Analysieren von Trends

Du kannst mit den Daten aus der API arbeiten, um Trends in den letzten 28 Tagen zu identifizieren, oder wenn du Daten aus vorherigen API-Aufrufen über einen längeren Zeitraum gespeichert haben.

Beispiel

Im folgenden Beispiel wird die orgMetrics-Funktion so aktualisiert, dass sie die Gesamtzahl und die durchschnittliche Anzahl der aktiven und beteiligten Benutzer pro Woche extrahiert. Anschließend könnten diese Daten verwendet werden, um Änderungen im Laufe der Zeit nachzuverfolgen. In diesem Beispiel werden die Daten verwendet, die direkt von der API zurückgegeben werden. Es sind keine gespeicherten Daten erforderlich.

Neue Schritte werden fett annotiert.

JavaScript

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  // **Create an object to store data for each week**
  let userTrends ={
    week1: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week2: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week3: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week4: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
  };

 // **Iterate over the data**
 for (let i =0; i<copilotUsage.length; i++) {
    // **Determine the week number (1-4) based on the index**
    const week = Math.ceil((i+1)/7);
    // **Increment userTrends for the current week**
    userTrends[`week${week}`].days += 1;
    userTrends[`week${week}`].activeUsers += copilotUsage[i].total_active_users;
    userTrends[`week${week}`].engagedUsers += copilotUsage[i].total_engaged_users;
  }

 // **Calculate the average number of active and engaged users per day for each week, rounded to two decimal places**
 for (const week in userTrends) {
  userTrends[week].avgActiveUsers = (userTrends[week].activeUsers / userTrends[week].days).toFixed(2);
  userTrends[week].avgEngagedUsers = (userTrends[week].engagedUsers / userTrends[week].days).toFixed(2);
  }

  // Output to the console
  console.log(userTrends);
}

async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });
  const copilotUsage = resp.data;

Call the API

  let userTrends ={
    week1: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week2: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week3: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week4: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
  };

Create an object to store data for each week

 for (let i =0; i<copilotUsage.length; i++) {

Iterate over the data

    const week = Math.ceil((i+1)/7);

Determine the week number (1-4) based on the index

    userTrends[`week${week}`].days += 1;
    userTrends[`week${week}`].activeUsers += copilotUsage[i].total_active_users;
    userTrends[`week${week}`].engagedUsers += copilotUsage[i].total_engaged_users;
  }

Increment userTrends for the current week

 for (const week in userTrends) {
  userTrends[week].avgActiveUsers = (userTrends[week].activeUsers / userTrends[week].days).toFixed(2);
  userTrends[week].avgEngagedUsers = (userTrends[week].engagedUsers / userTrends[week].days).toFixed(2);
  }

Calculate the average number of active and engaged users per day for each week, rounded to two decimal places

  console.log(userTrends);
}

Output to the console

// Call the API
async function orgMetrics() {
  const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, {
    org: 'ORG',
    headers: {
      'X-GitHub-Api-Version': '2022-11-28'
    }
  });

  const copilotUsage = resp.data;

  // **Create an object to store data for each week**
  let userTrends ={
    week1: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week2: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week3: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
    week4: {
      days:0,
      activeUsers:0,
      engagedUsers:0,
    },
  };

 // **Iterate over the data**
 for (let i =0; i<copilotUsage.length; i++) {
    // **Determine the week number (1-4) based on the index**
    const week = Math.ceil((i+1)/7);
    // **Increment userTrends for the current week**
    userTrends[`week${week}`].days += 1;
    userTrends[`week${week}`].activeUsers += copilotUsage[i].total_active_users;
    userTrends[`week${week}`].engagedUsers += copilotUsage[i].total_engaged_users;
  }

 // **Calculate the average number of active and engaged users per day for each week, rounded to two decimal places**
 for (const week in userTrends) {
  userTrends[week].avgActiveUsers = (userTrends[week].activeUsers / userTrends[week].days).toFixed(2);
  userTrends[week].avgEngagedUsers = (userTrends[week].engagedUsers / userTrends[week].days).toFixed(2);
  }

  // Output to the console
  console.log(userTrends);
}

Lokales Ausführen des Skripts

Nachdem du das Skript mit node copilot.mjs ausgeführt hast, sollte die Ausgabe in deinem Terminal folgendermaßen angezeigt werden.

{
  week1: {
    days: 7,
    activeUsers: 174,
    engagedUsers: 174,
    avgActiveUsers: '24.86',
    avgEngagedUsers: '24.86'
  },
  week2: {
    days: 7,
    activeUsers: 160,
    engagedUsers: 151,
    avgActiveUsers: '22.86',
    avgEngagedUsers: '21.57'
  },
  week3: {
    days: 7,
    activeUsers: 134,
    engagedUsers: 123,
    avgActiveUsers: '19.14',
    avgEngagedUsers: '17.57'
  },
  week4: {
    days: 6,
    activeUsers: 143,
    engagedUsers: 132,
    avgActiveUsers: '23.83',
    avgEngagedUsers: '22.00'
  }
}

Analysieren der Nutzung im Laufe der Zeit mit der Copilot-Metrik-API

Wer kann dieses Feature verwenden?

In diesem Artikel

Einführung

Informationen zur Verfügbarkeit von Endpunkten

Voraussetzungen

1. Erstellen eines personal access token

2. Herstellen einer Verbindung mit der API

Beispiel

Lokales Ausführen des Skripts

3. Speichern der Daten

Beispiel

Lokales Ausführen des Skripts

4. Analysieren von Trends

Beispiel

Lokales Ausführen des Skripts