REST API を使用した使用状況レポート作成の自動化

従量制課金に移行した後、内部レポートシステムの有料 GitHub 機能の使用量とコストを自動的に追跡できます。たとえば、時間の経過に伴う支出の監視、請求書の調整、財務ツールや BI ツールへの使用状況データのフィードなどを行うことができます。

このチュートリアルでは、REST API を使用して課金使用状況データを取得し、期間またはコストセンターでフィルター処理し、ユーザー、組織、またはエンタープライズレベルで定期的なレポートを自動化する方法について説明します。また、生の使用状況データを意味のあるコスト分析情報に変換できるように、応答の主要なフィールドを解釈する方法についても説明します。

[前提条件]

このチュートリアルを開始する前に、次の点を確認してください。

任意のレポートレベルで課金データにアクセスできます。
- ユーザーレベルのレポート: アカウント所有者
- 組織レベルのレポート: 組織の所有者または請求管理者
- エンタープライズレベルのレポート: エンタープライズ管理者または課金マネージャー
REST API に対する認証済み要求の作成に慣れている。概要については、「REST API を使用して」を参照してください。
personal access token (classic) を使用して認証を行います。課金の使用状況エンドポイントでは、fine-grained personal access tokens はサポートされていません。

レポートのニーズに応じて、API から取得した使用状況データを格納および分析できる内部システム (スプレッドシート、データベース、BI ツールなど) にアクセスすることもできます。

手順 1: レポートするレベルを決定する

レポートするアカウントレベルを決定します。これにより、 呼び出す REST API エンドポイント と、レポートに含める内容が決まります。

目標に最も適したレポートレベルを選択します。

報告レベル	いつ使用するか

          **User** | たとえば、個人の使用状況やコストを把握するために、1 つのアカウントのレポートが必要です。 |

レポートレベルを選択したら、次の手順で対応するエンドポイントを使用して使用状況データを取得し、自動レポートを作成します。

手順 2: 有料製品の使用状況データを取得する

レポートするレベルを決定したら、REST API を使用して、有料 GitHub 製品の使用状況データを取得します。すべてのエンドポイントについては、課金の使用状況を参照してください。

GitHub には、次の 2 種類の課金使用状況データが用意されています。

        **使用状況の概要** – すべての有料製品の使用状況とコストデータの集計。

        **Premium 要求の使用量** – クォータや超過分の使用量など、Premium 要求の詳細な使用状況と課金データ。

ほとんどのレポートシナリオでは、 使用状況の概要 から始めて全体的な使用状況と支出を把握し、Premium 要求の使用量に関するより深い分析情報が必要な場合は、Premium 要求の使用状況データを使用します。

使用状況の概要を取得する

手順 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 の値に設定します。

          **データ変数 product.prodname_cli %} の使用例**

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

このエンドポイントは、現在の年のすべての有料製品の集計された使用状況データを既定で返します。各エントリには、製品、ユニットタイプ、使用数量、請求金額などの情報が含まれます。

同じ方法を使用して、そのアカウントレベルの同等のエンドポイントを呼び出すことによって、組織またはユーザーの使用状況の概要を取得できます。

Premium 要求の使用状況を取得する

Premium 要求の使用量について具体的に報告する必要がある場合は、同じアカウントレベルで premium_request/usage エンドポイントを使用します。このエンドポイントは、含まれている使用量、請求された超過分、残りのクォータなどの追加の詳細を提供します。

次の手順では、期間またはコストセンターで使用状況データをフィルター処理して、より対象を絞ったレポートを生成する方法について説明します。

手順 3: 期間またはコストセンターで使用状況データをフィルター処理する

既定では、使用状況の概要エンドポイントは 、現在の年のデータを返します。より多くの対象となるレポートを生成したり、時間の経過に伴う傾向を分析したりするには、クエリパラメーターを使用して使用状況データをフィルター処理できます。

期間でフィルタする

返される使用状況データを制限するには、次のクエリパラメーターを 1 つ以上指定します。

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などのフィールドを集計します。

詳細な例と製品固有の計算については、課金とライセンスの概要を参照してください。