使用 REST API 自动化使用报告 - GitHub 文档

在您转为计量计费后，您可能希望在内部报告系统中自动跟踪付费 GitHub 功能的使用和费用。例如，您可能想监控随时间的支出、对账发票，或将使用数据馈送到财务或 BI 工具中。

在本教程中，您将学习如何使用 REST API 检索计费使用数据、按时间段或成本中心筛选数据，并在用户、组织或企业层级自动生成定期报告。您还将了解如何解释响应中的关键字段，以便将原始使用数据转化为有意义的成本洞察。

先决条件

在开始本教程之前，请确保

您拥有在要报告的层级上访问计费数据的权限
- 用户级报告：账户持有人
- 组织级报告：组织所有者或计费管理员
- 企业级报告：企业管理员或计费管理员
您已经熟悉对 REST API 进行身份验证请求。要了解入门，请参阅使用 REST API。
您使用个人访问令牌（经典）进行身份验证。计费使用端点不支持细粒度个人访问令牌。

根据您的报告需求，您可能还需要访问内部系统（如电子表格、数据库或 BI 工具），以便存储和分析从 API 获取的使用数据。

步骤 1：决定报告的层级

决定要报告的账户层级。这决定了您将调用的 REST API 端点以及报告中将包含的内容。

选择最符合您目标的报告层级

报告层级	何时使用
用户	您想要针对单个账户的报告，例如了解个人使用情况和费用。
组织	您想跟踪特定组织的使用和费用，例如用于团队级监控或内部收费。
企业	您想要跨多个组织的统一视图，例如用于财务报告或成本中心报告。

选择报告层级后，您将在下一步使用相应的端点检索使用数据并构建自动化报告。

步骤 2：检索付费产品的使用数据

确定要报告的层级后，使用 REST API 检索付费 GitHub 产品的使用数据。所有端点请参阅计费使用。

GitHub 提供两类计费使用数据

使用摘要 – 所有付费产品的聚合使用和费用数据。
高级请求使用 – 高级请求的详细使用和计费数据，包括配额和超额使用。

在大多数报告场景中，您将先使用 使用摘要 了解整体使用和支出，然后在需要深入了解高级请求消耗时使用高级请求使用数据。

检索使用摘要

使用与步骤 1 中选择的报告层级对应的使用摘要端点。

例如，要检索企业的使用摘要，请发送请求至

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

您必须对该端点的请求进行身份验证。

使用 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

将 ENTERPRISE 替换为企业 slug，并将 GITHUB_TOKEN 环境变量设置为具有所需计费权限的个人访问令牌。

使用 GitHub CLI 示例

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

此端点默认返回当前年份所有付费产品的聚合使用数据。每条记录包括产品、单位类型、使用数量和计费金额等信息。

您可以使用相同的方法，通过调用对应账户层级的等效端点来检索组织或用户的使用摘要。

检索高级请求使用

如果需要专门报告高级请求消耗，请使用相同账户层级的 premium_request/usage 端点。该端点提供包括已包含使用、计费超额和剩余配额等额外细节。

在下一步，您将学习如何按时间段或成本中心筛选使用数据，以生成更有针对性的报告。

步骤 3：按时间段或成本中心筛选使用数据

默认情况下，使用摘要端点返回当前年度的数据。要生成更有针对性的报告或随时间分析趋势，您可以使用查询参数筛选使用数据。

按时间段筛选

您可以通过指定以下一个或多个查询参数来限制返回的使用数据

year
month
day
hour

例如，要检索特定月份的使用数据，请在请求中包含 year 和 month 参数。

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

按时间段筛选在以下情况下很有用：

生成每月或每日使用报告
比较变更前后的使用情况，例如启用新功能后
对特定计费周期的使用进行对账

按成本中心筛选（仅企业）

如果您检索企业级使用数据，还可以使用 cost_center_id 查询参数按成本中心筛选结果。

按成本中心筛选可以帮助您

将使用和费用归属到特定团队或业务单元
为财务或高层利益相关者生成成本中心特定报告

成本中心筛选仅在企业使用摘要端点中可用。

在下一步，您将学习如何自动化这些 API 调用以生成定期使用报告。

步骤 4：自动化定期使用报告

确定要收集的使用数据及其筛选方式后，您可以通过定期运行相同的 API 请求来自动化报告。

常见的自动化模式包括

运行计划的 API 请求（例如每日或每月）以收集使用数据
将结果存储在内部系统中，如数据库、电子表格或 BI 工具
使用数据监控趋势、检测使用变化或支持成本审查

自动化报告时，一致性很重要。每次使用相同的报告层级、筛选条件和时间范围，以便使用趋势在时间上可比较。

例如，您可以

每月运行一次企业级使用摘要，以跟踪总体支出
生成成本中心特定报告，用于内部分摊或展示
在启用新付费功能后监控使用增长

在下一步，您将学习如何解释 API 返回的使用和费用字段，以便将原始数据转化为有意义的洞察。

步骤 5：解释 API 响应中的使用和费用字段

使用摘要响应同时包含使用和费用信息。了解这些字段之间的关系有助于解释支出、已包含使用以及计费超额。

每个使用项包括

quantity（数量），表示特定产品和单位类型的使用量
netAmount（净额），表示该使用的计费费用
discountAmount（折扣额），表示被包含配额或折扣覆盖的使用量

一般而言

使用 quantity 了解消费了多少产品
使用 netAmount 了解计费了多少
使用 discountAmount 了解有多少使用被包括或获得折扣

例如，高数量但低 netAmount 可能表明大部分使用被包含配额覆盖，而 netAmount 随时间上升则可能表明付费使用增加。

不同产品使用不同的单位类型（例如分钟、千兆字节或请求）报告使用情况。若要计算特定产品的指标或复现先前计费平台的数值，可能需要按产品和单位类型筛选使用项并汇总结果。详细示例请参见下一步中的参考文档链接。

步骤 6：计算特定产品的使用指标

在某些情况下，您可能需要从使用摘要响应中计算特定产品的使用指标。这在您想为特定产品生成自定义报告或复现旧报表中使用的数值时尤为相关。

计算这些指标时，通常按 product 和 unitType 筛选使用项，然后汇总 quantity、netAmount 和 discountAmount 等字段。

有关详细示例和特定产品计算，请参见计费和许可简介。

使用 REST API 自动化使用情况报告

谁可以使用此功能？

本文内容