GitHub Enterprise Cloudの予算REST APIに、multi-user budgetに属する全ユーザーの消費状態を一括取得するendpointが追加された。従来はユーザーごとにAPI callが必要で、利用率に基づくfilterもできなかった。新endpointでは消費額、適用上限、個別overrideをpage単位で取得し、上限へ近い利用者だけを抽出できる。

何が変わったか

GET /enterprises/{enterprise}/settings/billing/budgets/{budget_id}/user-statesで、user_states、has_next_page、total_countを取得できる。各stateにはuser、consumed amount、target amountが含まれ、個別予算overrideがある場合はそのIDも確認できる。利用率の下限filter、特定userのfilter、消費量によるsortを使える。

変更前後の差

変更前は、対象者一覧を取得してから一人ずつ消費状況を照会するN+1型の処理が必要だった。大規模enterpriseではAPI call数と集計時間が増え、上限接近者を抽出する独自scriptが必要だった。変更後はbudget単位の一括endpointでpage処理でき、閾値を超えたユーザーへ直接絞り込める。

誰に影響するか

GitHub Enterprise CloudのEnterprise ownerとbilling managerが利用できる。対象は、全ユーザーへ適用するuniversal budgetと、cost centerに紐づくper-user budgetの両方である。Copilotなどusage-based billingを利用し、利用者別の上限、追加利用、例外budgetを運用する組織が主な対象となる。

期限

強制移行期限はない。既存のbudget管理APIも利用できるが、user別pollingを継続する理由は小さい。次回の予算監視script改修またはAPI version更新時に置き換える。

必要な対応

新endpointを使うtokenの権限とEnterprise owner・billing managerの役割を確認する。API versionは公式sampleで示されるversionを明示し、page終端をhas_next_pageで処理する。利用率80%、90%、100%などの閾値ごとに通知先と対応を決め、overrideがあるユーザーを別集計する。

実装・移行手順

  1. 現在のbudget一覧とmulti-user budget IDを取得する
  2. user別に繰り返す既存API callを特定する
  3. 新しいuser-states endpointを検証環境で呼び出す
  4. page処理、filter、sort、特定user検索を実装する
  5. consumed amountとtarget amountから利用率を計算する
  6. override budget IDを持つuserを別表示する
  7. 既存集計との件数・金額差を比較する
  8. 監視と通知を切り替え、旧pollingを停止する

失敗しやすい点

一pageだけ取得して全員とみなす、target amountがoverrideで変わる点を無視する、金額とtoken量を混同する、Enterprise全体のbudgetとcost center budgetを重複集計する、といった問題が起きやすい。利用率filterの境界値と通貨・小数処理も明示する必要がある。

リスク

通知漏れ、重複通知、override対象者への誤った制限、予算情報を閲覧できるtokenの漏えい、API version変更による集計停止がある。予算接近を検知しても、利用者へ一律停止をかけると重要業務を中断するため、例外承認と段階対応が必要である。

評価方法

  • 予算集計API call数
  • 全user取得に要する時間
  • page未取得による欠損件数
  • 閾値通知の遅延
  • override検出率
  • 旧集計との金額差
  • 上限超過者数と事前通知率
  • token権限レビュー結果
  • 監視jobのerror率

ロールバック

新endpointの結果に不整合がある場合は、旧user別取得を短期間だけ並行維持し、budget ID、page、filter、overrideの処理を確認する。通知はshadow modeから開始し、差異が解消するまで自動制限へ接続しない。取得失敗時は直近成功値を明示して表示し、古いデータを最新値として扱わない。

編集部分析

このAPI変更は画面上の新機能ではないが、usage-based billingを大規模運用する組織には実務効果が大きい。予算管理のボトルネックは総額より、誰がどの上限へ近づいているかを早く把握できないことにある。一括取得とfilterにより、監視を事後集計から事前介入へ移せる。

実務チェックリスト

  • [ ] multi-user budget IDを一覧化した
  • [ ] 新endpointの権限を確認した
  • [ ] 全pageを取得する処理を実装した
  • [ ] override budgetを識別した
  • [ ] 利用率閾値と通知先を決めた
  • [ ] 旧集計との照合を行った
  • [ ] 自動制限の前にshadow運用した
  • [ ] API versionと失敗時表示を固定した

一次情報