Después de realizar la transición a la facturación medida, es posible que desee hacer un seguimiento automático de los costos y el uso de las funciones pagadas de GitHub en los sistemas de informes internos. Por ejemplo, es posible que quiera supervisar el gasto con el tiempo, conciliar facturas o proporcionar datos de uso a las herramientas de finanzas o BI.
En este tutorial, aprenderá a usar la API REST para recuperar datos de uso de facturación, filtrarlos por período de tiempo o centro de costos y automatizar informes periódicos en el nivel de usuario, organización o empresa. También aprenderá a interpretar los campos clave en la respuesta para que pueda convertir los datos de uso sin procesar en conclusiones de costos significativas.
Prerrequisitos
Antes de comenzar este tutorial, asegúrese de que:
-
Tiene acceso a los datos de facturación en el nivel en el que desea informar:
- Informes de nivel de usuario: titular de la cuenta
- Informes de nivel de organización: propietario de la organización o administrador de facturación
- Informes de nivel empresarial: administrador de empresa o administrador de facturación
-
Está familiarizado con la realización de solicitudes autenticadas a la API REST. Para obtener una introducción, consulta Mediante la API de REST.
-
Te autenticas mediante un personal access token (classic). Los puntos de conexión de uso de facturación no admiten fine-grained personal access tokens.
En función de sus necesidades de informes, también puede que desee acceder a un sistema interno (como una hoja de cálculo, una base de datos o una herramienta de BI), donde puede almacenar y analizar los datos de uso recuperados de la API.
Paso 1: Decidir el nivel en el que se va a informar
Decida en qué nivel de cuenta desea informar. Esto determina qué punto de conexión de la API REST llamarás y qué incluirá tu informe.
Elija el nivel de informes que mejor se adapte a su objetivo:
| Nivel de informes | Cuándo se debe usar |
|---|
**Usuario** | Quiere un informe de una sola cuenta, por ejemplo, para comprender el uso personal y los costos. |
| Organización | Quieres realizar un seguimiento del uso y los costos de una organización específica, por ejemplo, para la supervisión o reparto de costos a nivel de equipo. | | Empresa | Quiere una vista centralizada en varias organizaciones, por ejemplo, para los informes financieros o los informes del centro de costos. |
Una vez que haya elegido un nivel de informes, usará el punto de conexión correspondiente en el paso siguiente para recuperar los datos de uso y crear un informe automatizado.
Paso 2: Recuperar datos de uso de productos de pago
Después de decidir sobre qué nivel desea realizar el informe, use la API REST para recuperar los datos de uso de los productos pagos de GitHub. Para todos los endpoints, vea Uso de facturación.
GitHub proporciona dos tipos de datos de uso de facturación:
-
**Resúmenes de** uso: datos agregados de uso y costo para todos los productos de pago. -
**Uso de solicitudes Premium** : datos detallados de uso y facturación de las solicitudes Premium, incluidas las cuotas y el uso por encima del límite.
En la mayoría de los escenarios de informes, empezará con un resumen de uso para comprender el uso general y el gasto y, a continuación, usará los datos de uso de solicitudes Premium cuando necesite información más detallada sobre el consumo de solicitudes Premium.
Recuperación de un resumen de uso
Utilice el punto de conexión de resumen de uso que se corresponda con el nivel de informes que eligió en el paso 1.
Por ejemplo, para recuperar un resumen de uso de una empresa, realice una solicitud a:
/enterprises/{enterprise}/settings/billing/usage/summary
Debe autenticar la solicitud en este punto de conexión.
**Ejemplo de uso de 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
Reemplace ENTERPRISE por el slug de la empresa y configure la variable de entorno GITHUB_TOKEN en un personal access token con los permisos de facturación necesarios.
**Ejemplo usando el GitHub CLI**
gh api \
-H "X-GitHub-Api-Version: 2022-11-28" \
/enterprises/ENTERPRISE/settings/billing/usage/summary
Este punto de conexión devuelve datos de uso agregados para todos los productos de pago para el año actual de forma predeterminada. Cada entrada incluye información como el producto, el tipo de unidad, la cantidad utilizada y el importe facturado.
Puede usar el mismo enfoque para recuperar resúmenes de uso para una organización o usuario llamando al punto de conexión equivalente para ese nivel de cuenta.
Recuperación del uso de solicitudes Premium
Si necesita hacer un informe sobre el consumo de solicitudes premium, utilice el endpoint premium_request/usage para el mismo nivel de cuenta. Este punto de conexión proporciona detalles adicionales, como el uso incluido, las sobrecargas facturadas y la cuota restante.
En el paso siguiente, aprenderá a filtrar los datos de uso por período de tiempo o centro de costos para que pueda generar informes más específicos.
Paso 3: Filtrar los datos de uso por período de tiempo o centro de costos
De forma predeterminada, los endpoints de resumen de uso devuelven datos para el año actual. Para generar informes más específicos o analizar tendencias a lo largo del tiempo, puede filtrar los datos de uso mediante parámetros de consulta.
Filtrar por período de tiempo
Puede limitar los datos de uso devueltos especificando uno o varios de los parámetros de consulta siguientes:
yearmonthdayhour
Por ejemplo, para recuperar los datos de uso de un mes específico, incluya los year parámetros y month en la solicitud:
GET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12
El filtrado por período de tiempo es útil cuando desea:
- Generación de informes de uso mensual o diario
- Comparar el uso antes y después de un cambio, como habilitar una nueva característica
- Conciliar el uso con las facturas para un periodo de facturación específico
Filtrar por centro de costos (solo empresa)
Si va a recuperar datos de uso de nivel empresarial, también puede filtrar los resultados por centro de costos mediante el cost_center_id parámetro de consulta.
El filtrado por centro de costos le permite:
- Atribuir el uso y los costos a equipos o unidades de negocio específicas
- Generación de informes específicos del centro de costos para las partes interesadas de finanzas o liderazgo
El filtrado del centro de costos solo está disponible para los puntos de conexión de resumen de uso empresarial.
En el paso siguiente, aprenderá a automatizar estas llamadas API para generar informes de uso periódicos.
Paso 4: Automatizar informes de uso periódicos
Una vez que haya identificado los datos de uso que desea recopilar y cómo filtrarlos, puede automatizar los informes mediante la ejecución de las mismas solicitudes de API según una programación periódica.
Entre los patrones de automatización comunes se incluyen los siguientes:
- Ejecución de solicitudes de API programadas (por ejemplo, diarias o mensuales) para recopilar datos de uso
- Almacenar los resultados en un sistema interno, como una base de datos, una hoja de cálculo o una herramienta de BI
- Uso de los datos para supervisar las tendencias, detectar variaciones en el uso o respaldar revisiones de costos
Al automatizar informes, la coherencia es importante. Use el mismo nivel de informes, filtros y intervalos de tiempo cada vez para que las tendencias de uso sean comparables con el tiempo.
Por ejemplo, es posible que:
- Ejecución de un resumen de uso mensual de nivel empresarial para realizar un seguimiento del gasto total
- Generar informes específicos del centro de costos para el cobro revertido interno o showback
- Supervisión del crecimiento del uso después de habilitar nuevas características de pago
En el paso siguiente, aprenderá a interpretar los campos de uso y costo devueltos por la API para que pueda convertir los datos sin procesar en información significativa.
Paso 5: Interpretar los campos de uso y costo en la respuesta de la API
La respuesta de resumen de uso incluye información sobre el uso y el costo . Comprender cómo se relacionan estos campos entre sí le ayuda a interpretar el gasto, el uso incluido y los usos facturados por encima del límite.
Cada elemento de uso incluye:
-
**Cantidad**, que representa la cantidad de uso de un producto y un tipo de unidad específicos. -
**NetAmount**, que representa el costo facturado por ese uso - Un discountAmount, que representa el uso cubierto por cuotas o descuentos incluidos
En general:
- Usar cantidad para comprender la cantidad de un producto consumido
- Utilice netAmount para comprender lo que fue facturado
- Use discountAmount para comprender cuánto del uso se incluyó o descontó.
Por ejemplo, una cantidad alta con un netAmount bajo puede indicar que la mayoría del uso se ha cubierto por cuotas incluidas, mientras que un aumento de netAmount a lo largo del tiempo puede indicar un aumento del uso pagado.
Diferentes productos notifican el uso mediante diferentes tipos de unidad (como minutos, gigabytes o solicitudes). Para calcular métricas específicas del producto o reproducir valores de la plataforma de facturación anterior, es posible que tenga que filtrar los elementos de uso por tipo de producto y unidad y agregar los resultados. Los ejemplos detallados están disponibles en la documentación de referencia vinculada en el paso siguiente.
Paso 6: Cálculo de métricas de uso específicas del producto
En algunos casos, es posible que tenga que calcular las métricas de uso específicas del producto a partir de la respuesta de resumen de uso. Esto es más relevante si desea generar informes personalizados para un producto específico o reproducir valores usados en los informes heredados.
Para calcular estas métricas, normalmente se filtran los elementos de uso por product y unitType, después se agregan campos como quantity, netAmounty discountAmount.
Para obtener ejemplos detallados y cálculos específicos del producto, consulte Migración desde los puntos de conexión usados para la plataforma de facturación anterior.