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

了解如何使用 REST API 自动报告付费功能使用情况。

谁可以使用此功能？

Enterprise owners, organization owners, and billing managers

新的计费平台现可供所有用户使用。

在本文中

转换到按流量计费后，可能需要在内部报表系统中自动跟踪付费 GitHub 功能的使用情况和成本。 例如，你可能希望监视随时间推移的花费、对帐发票或将使用情况数据馈送到财务或 BI 工具中。

本教程介绍如何使用 REST API 检索计费使用情况数据、按时间段或成本中心对其进行筛选，以及自动执行用户、组织或企业级别的定期报告。 你还将了解如何解释响应中的关键字段，以便可以将原始使用情况数据转换为有意义的成本见解。

先决条件

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

  • 可以访问要报告的级别的计费数据：

    • 用户级报告：账户持有人
    • 组织级别报表：组织所有者或账单管理员
    • 企业级报表：企业管理员或财务经理

  • 你熟悉向 REST API 发出经过身份验证的请求。 有关简介，请参阅“使用 REST API”。

  • 使用 personal access token (classic) 进行身份验证。 计费使用情况终结点不支持 fine-grained personal access tokens。

根据报告需求，你可能还需要访问内部系统（例如电子表格、数据库或 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 替换为企业短名称，并将 GITHUB_TOKEN 环境变量设置为具有所需计费权限的 personal access 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 响应中的使用情况和成本字段

使用情况摘要响应包括 使用情况 和 成本 信息。 了解这些字段如何相互关联有助于解释支出、包括使用情况和计费超额。

每个使用项包括：

  • 一个 数量，表示特定产品和单位类型的使用量
  • netAmount，表示该使用量的计费成本
  •         **discountAmount**，表示包含在配额或折扣内的使用量

一般而言：

  • 使用 数量 了解产品消耗量
  • 使用 netAmount 了解计费内容
  • 使用 discountAmount 来了解包含的使用量或折扣金额的多少.

例如，具有低 netAmount 的高数量可能表示包含的配额覆盖了大多数使用量，而随着时间的推移，netAmount 的上升可能表示付费使用量增加。

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

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

在某些情况下，可能需要从使用情况摘要响应中计算特定于产品的使用情况指标。 如果要为特定产品生成自定义报表或重现旧报表中使用的值，则这是最相关的。

若要计算这些指标，通常按product和unitType筛选使用情况项，然后聚合字段，例如quantity、netAmount和discountAmount。

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