Automatisation des rapports d’utilisation avec l’API REST

Après avoir effectué la transition vers la facturation mesurée, vous pouvez suivre de façon automatique l'utilisation et les coûts des fonctionnalités payantes GitHub dans vos systèmes de reporting internes. Par exemple, vous pouvez surveiller les dépenses au fil du temps, rapprocher les factures ou alimenter les données d’utilisation dans des outils financiers ou décisionnels.

Dans ce tutoriel, vous allez apprendre à utiliser l’API REST pour récupérer les données d’utilisation de facturation, les filtrer par période ou centre de coûts et automatiser les rapports périodiques au niveau de l’utilisateur, de l’organisation ou de l’entreprise. Vous allez également apprendre à interpréter les champs clés dans la réponse afin de pouvoir transformer les données d’utilisation brutes en insights significatifs sur les coûts.

Prerequisites

Avant de commencer ce tutoriel, assurez-vous que :

Vous avez accès aux données de facturation au niveau sur lequel vous souhaitez signaler les éléments suivants :
- Rapports au niveau de l’utilisateur : titulaire du compte
- Rapports au niveau de l’organisation : propriétaire de l’organisation ou responsable de facturation
- Rapports au niveau de l’entreprise : administrateur d’entreprise ou responsable de facturation
Vous êtes familiarisé avec l’établissement de requêtes authentifiées auprès de l’API REST. Pour une introduction, consultez En utilisant l’API REST.
Vous vous authentifiez à l’aide d’un personal access token (classic). Les points d'utilisation des terminaux de facturation ne sont pas compatibles avec fine-grained personal access tokens.

Selon vos besoins en matière de création de rapports, vous pouvez également vouloir accéder à un système interne (tel qu'une feuille de calcul, une base de données ou un outil de BI) dans lequel vous pouvez stocker et analyser les données d'utilisation récupérées à partir de l'API.

Étape 1 : Déterminer le niveau à signaler

Déterminez le niveau de compte sur lequel vous souhaitez effectuer un rapport. Cela détermine le point de terminaison de l’API REST que vous allez appeler et ce que votre rapport inclura.

Choisissez le niveau de création de rapports qui correspond le mieux à votre objectif :

Niveau de rapport	Quand l′utiliser ?

          **Utilisateur** | Vous souhaitez un rapport pour un compte unique, par exemple pour comprendre l’utilisation et les coûts personnels. |

| Organisation | Vous souhaitez suivre l’utilisation et les coûts d’une organisation spécifique, par exemple pour la supervision ou la rétrofacturation au niveau de l’équipe. | | Entreprise | Vous souhaitez une vue centralisée sur plusieurs organisations, par exemple pour la création de rapports financiers ou la création de rapports de centre de coûts. |

Une fois que vous avez choisi un niveau de création de rapports, vous allez utiliser le point de terminaison correspondant à l’étape suivante pour récupérer les données d’utilisation et générer un rapport automatisé.

Étape 2 : Récupérer les données d’utilisation pour les produits payants

Une fois que vous avez décidé quel niveau rapporter, utilisez REST API pour récupérer les données d’utilisation pour les produits payants de GitHub. Pour tous les points de terminaison, consultez Utilisation facturée.

GitHub fournit deux types de données d'utilisation de la facturation :

        **Résumés de l’utilisation** : données d’utilisation agrégées et de coût pour tous les produits payants.

        **Utilisation des demandes Premium** : données détaillées d’utilisation et de facturation pour les demandes Premium, y compris les quotas et l’utilisation excessive.

Dans la plupart des scénarios de création de rapports, vous allez commencer par un résumé de l’utilisation pour comprendre l’utilisation globale et les dépenses, puis utiliser les données d’utilisation des demandes Premium lorsque vous avez besoin d’informations plus approfondies sur la consommation de demandes Premium.

Récupérer un résumé de l’utilisation

Utilisez le point de terminaison récapitulative de l’utilisation qui correspond au niveau de création de rapports que vous avez choisi à l’étape 1.

Par exemple, pour récupérer un résumé de l’utilisation d’une entreprise, effectuez une demande pour :

/enterprises/{enterprise}/settings/billing/usage/summary

Vous devez authentifier votre demande auprès de ce point de terminaison.

          **Exemple utilisant curl**

curl -L \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary

Remplacez ENTERPRISE par le slug d’entreprise et définissez la GITHUB_TOKEN variable d’environnement sur un personal access token avec les autorisations de facturation requises.

          **Exemple utilisant le GitHub CLI**

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /enterprises/ENTERPRISE/settings/billing/usage/summary

Ce point de terminaison retourne les données d’utilisation agrégées pour tous les produits payants pour l’année en cours par défaut. Chaque entrée comprend des informations telles que le produit, le type d’unité, la quantité utilisée et le montant facturé.

Vous pouvez utiliser la même approche pour récupérer des résumés d’utilisation pour une organisation ou un utilisateur en appelant le point de terminaison équivalent pour ce niveau de compte.

Consulter l'utilisation de la requête Premium

Si vous devez signaler spécifiquement la consommation de demandes Premium, utilisez le premium_request/usage point de terminaison pour le même niveau de compte. Ce point de terminaison fournit des détails supplémentaires tels que l’utilisation incluse, les dépassements facturés et le quota restant.

À l’étape suivante, vous allez apprendre à filtrer les données d’utilisation par période ou centre de coûts afin de générer des rapports plus ciblés.

Étape 3 : Filtrer les données d’utilisation par période ou centre de coûts

Par défaut, les points de terminaison récapitulatives de l’utilisation retournent des données pour l’année en cours. Pour générer des rapports plus ciblés ou analyser des tendances au fil du temps, vous pouvez filtrer les données d’utilisation à l’aide de paramètres de requête.

Filtrer par période

Vous pouvez limiter les données d’utilisation retournées en spécifiant un ou plusieurs des paramètres de requête suivants :

year
month
day
hour

Par exemple, pour récupérer des données d’utilisation pour un mois spécifique, incluez les paramètres year et month dans votre demande :

GET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12

Le filtrage par période est utile lorsque vous souhaitez :

Générer des rapports d’utilisation mensuels ou quotidiens
Comparer l’utilisation avant et après une modification, par exemple l’activation d’une nouvelle fonctionnalité
Rapprocher l'utilisation avec les factures pour une période de facturation spécifique

Filtrer par centre de coûts (entreprise uniquement)

Si vous récupérez des données d’utilisation au niveau de l’entreprise, vous pouvez également filtrer les résultats par centre de coûts à l’aide du cost_center_id paramètre de requête.

Le filtrage par centre de coûts vous permet de :

Attribuer l’utilisation et les coûts à des équipes ou des unités commerciales spécifiques
Générer des rapports spécifiques au centre de coûts pour les parties prenantes en finance ou en leadership

Le filtrage du centre de coûts est disponible uniquement pour les points de terminaison récapitulatives de l’utilisation de l’entreprise.

À l’étape suivante, vous allez apprendre à automatiser ces appels d’API pour générer des rapports d’utilisation périodiques.

Étape 4 : Automatiser les rapports d’utilisation périodiques

Une fois que vous avez identifié les données d’utilisation que vous souhaitez collecter et comment les filtrer, vous pouvez automatiser vos rapports en exécutant les mêmes demandes d’API selon une planification périodique.

Les modèles d’automatisation courants sont les suivants :

Exécution de requêtes d’API planifiées (par exemple, quotidiennes ou mensuelles) pour collecter des données d’utilisation
Stockage des résultats dans un système interne tel qu’une base de données, une feuille de calcul ou un outil décisionnel
Utilisation des données pour surveiller les tendances, détecter les modifications apportées à l’utilisation ou prendre en charge les révisions des coûts

Lors de l’automatisation des rapports, la cohérence est importante. Utilisez le même niveau de création de rapports, filtres et intervalles de temps chaque fois pour que les tendances d’utilisation soient comparables au fil du temps.

Par exemple, vous pouvez :

Exécuter un résumé mensuel de l’utilisation au niveau de l’entreprise pour suivre les dépenses globales
Générer les rapports spécifiques au centre de coûts pour la rétrofacturation interne ou le showback
Surveiller la croissance de l’utilisation après l’activation de nouvelles fonctionnalités payantes

À l’étape suivante, vous allez apprendre à interpréter les champs d’utilisation et de coût retournés par l’API afin de transformer les données brutes en insights significatifs.

Étape 5 : Interpréter les champs d’utilisation et de coût dans la réponse de l’API

La réponse récapitulative de l’utilisation inclut à la fois les informations d’utilisation et de coût . Comprendre comment ces champs se rapportent les uns aux autres vous aide à interpréter les dépenses, l’utilisation incluse et les dépassements facturés.

Chaque élément d’utilisation comprend les éléments suivants :

        **Quantité,** qui représente la quantité d’utilisation d’un produit et d’un type d’unité spécifique

        **NetAmount**, qui représente le coût facturé pour cette utilisation

Un discountAmount, qui représente l’utilisation couverte par des quotas ou des remises inclus

En général :

Utiliser la quantité pour comprendre la quantité d’un produit consommé
Utiliser netAmount pour comprendre ce qui a été facturé
Utiliser discountAmount pour comprendre la quantité d’utilisation incluse ou remise

Par exemple, une quantité élevée avec un netAmount faible peut indiquer que la plupart des utilisations ont été couvertes par des quotas inclus, tandis qu’un netAmount croissant au fil du temps peut indiquer une utilisation accrue des salaires.

Différents produits signalent l’utilisation à l’aide de différents types d’unités (par exemple, minutes, gigaoctets ou demandes). Pour calculer des métriques spécifiques au produit ou reproduire des valeurs à partir de la plateforme de facturation précédente, vous devrez peut-être filtrer les éléments d’utilisation par type de produit et d’unité et agréger les résultats. Des exemples détaillés sont disponibles dans la documentation de référence liée à l’étape suivante.

Étape 6 : Calculer les métriques d’utilisation spécifiques au produit

Dans certains cas, vous devrez peut-être calculer les métriques d’utilisation spécifiques au produit à partir de la réponse récapitulative de l’utilisation. Cela est le plus pertinent si vous souhaitez générer des rapports personnalisés pour un produit spécifique ou reproduire les valeurs utilisées dans les rapports hérités.

Pour calculer ces métriques, vous filtrez généralement les éléments d’utilisation, product``unitTypepuis agréger des champs tels que quantity, netAmountet discountAmount.

Pour obtenir des exemples détaillés et des calculs spécifiques au produit, consultez Migration à partir des points de terminaison utilisés pour la plateforme de facturation précédente.