Analyse de l’utilisation au fil du temps avec l’API de métriques Copilot

Découvrez comment vous connecter à l’API, stocker des données et analyser les tendances d’utilisation.

Qui peut utiliser cette fonctionnalité ?

Organization owners, enterprise owners, and billing managers

GitHub Copilot Business or GitHub Copilot Enterprise

Dans cet article

Introduction

Vous pouvez utiliser le Points d'accès à l'API REST pour les mesures de Copilot pour voir comment les utilisateurs adoptent GitHub Copilot. Lors du déploiement de GitHub Copilot, il est utile d’afficher ces tendances pour vérifier que les utilisateurs utilisent les licences qui leur ont été attribuées, pour voir quelles fonctionnalités ils utilisent et pour comprendre l’effet du plan d'activation de votre entreprise sur les développeurs.

L’API comprend :

  • Données des 28 derniers jours
  • Nombre d’utilisateurs actifs et d’utilisateurs engagés
  • Répartitions par langue et IDE
  • Option permettant d’afficher les métriques d’une entreprise, d’une organisation ou d’une équipe

Si vous utilisez actuellement Points de terminaison d'API REST pour les métriques d'utilisation de GitHub Copilot, nous vous recommandons de migrer vers le Points d'accès à l'API REST pour les mesures de Copilot dès que possible.

Ce guide montre comment interroger l’API, stocker des données et analyser une tendance pour connaître les modifications apportées au nombre d’utilisateurs par semaine. Les exemples de ce guide utilisent le point de terminaison d’une organisation, mais vous pouvez adapter les exemples pour répondre à vos besoins.

À propos de la disponibilité des points de terminaison

Les points de terminaison sont disponibles pour obtenir des données pour une entreprise, une organisation, une équipe d’organisation ou une équipe d’entreprise.

  • Si vous avez un abonnement GitHub Copilot Business ou GitHub Copilot Enterprise dans le cadre d’une organisation ou d’une entreprise standard, vous pouvez utiliser les points de terminaison pour une entreprise, une organisation ou une équipe d’organisation. Vous n’avez pas accès aux équipes d’entreprise, sauf si vous êtes inscrit(e) dans une préversion.
  • Si vous utilisez une entreprise dédiée pour GitHub Copilot Business, c’est-à-dire un compte d'entreprise sans possibilité de créer des organisations, vous pouvez utiliser les points de terminaison pour une entreprise ou une équipe d’entreprise.

Prérequis

1. Créer un personal access token

Dans notre exemple, pour obtenir des métriques pour une organisation, nous allons créer un personal access token (classic) avec l’étendue manage_billing:copilot. Consultez Gestion de vos jetons d'accès personnels.

Si vous utilisez un autre point de terminaison, vous aurez peut-être besoin d’étendues différentes. Consultez Points d'accès à l'API REST pour les mesures de Copilot.

2. Se connecter à l’API

Nous allons appeler l’API à partir d’un script et enregistrer la réponse sous forme de variable. Nous pouvons ensuite stocker les données en externe et analyser les tendances dans les données.

L’exemple suivant utilise le client Octokit pour JavaScript. Vous pouvez utiliser d’autres méthodes pour appeler l’API, comme cURL ou GitHub CLI.

Exemple

Dans cet exemple :

  • Remplacez YOUR_TOKEN par votre personal access token.
  • Remplacez YOUR_ORG par le nom de votre organisation, par exemple octo-org.
JavaScript
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();

Exécuter le script localement

Pour tester le script localement, enregistrez le fichier en tant que copilot.mjs, puis exécutez node copilot.mjs.

Important

Le type de fichier .mjs est important. L’instruction import { Octokit } peut ne pas fonctionner avec un fichier .js standard.

Dans votre terminal, vous devriez voir une sortie avec un tableau JSON comme suit.

[
  {
    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. Stocker les données

Pour analyser les tendances sur plus de 28 jours, vous devez :

  • Appeler l’API quotidiennement, à l’aide d’une tâche cron ou d’un workflow GitHub Actions planifié.
  • Stocker des données localement ou avec un service de base de données tel que MySQL.
  • Interroger les données pour identifier les tendances au fil du temps.

Exemple

Dans cet exemple, nous allons enregistrer les données dans un fichier .json local. Pour ce faire, nous allons importer certains modules pour utiliser des fichiers et mettre à jour la fonction orgMetrics pour enregistrer les données de réponse.

La fonction enregistre de nouvelles données retournées chaque jour, sans remplacer les anciennes données dans le fichier.

Les nouvelles étapes sont annotées en gras.

JavaScript
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();

Exécuter le script localement

Après avoir exécuté le script avec node copilot.mjs, vous devriez avoir un nouveau fichier dans votre répertoire appelé copilotMetricsData.json. Ce fichier doit contenir les données de la réponse de l’API.

Si vous exécutez à nouveau le script le lendemain, il ne devrait enregistrer dans le fichier que les données d’une seule journée.

Vous pouvez utiliser les données de l’API pour identifier les tendances au cours des 28 derniers jours ou, si vous avez stocké des données à partir d’appels d’API précédents, sur une période plus longue.

Exemple

Dans l’exemple suivant, nous mettons à jour la fonction orgMetrics pour extraire le nombre total et moyen d’utilisateurs actifs et engagés par semaine. Nous pourrions ensuite utiliser ces données pour suivre les modifications au fil du temps. Cet exemple utilise les données retournées directement à partir de l’API et ne nécessite pas de données stockées.

Les nouvelles étapes sont annotées en gras.

JavaScript
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);
}

Exécuter le script localement

Après avoir exécuté le script avec node copilot.mjs, vous devez voir la sortie dans votre terminal comme suit.

{
  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'
  }
}