🏢

Check! APIでGitHub Enterpriseのライセンス（シート）使用状況を取得する

2024/01/26に公開

Prologue

こんにちは、@dz_ こと、岩永かづみです。

GitHub Enterpriseのライセンスのシート利用状況は、GitHub.comのGUIから確認できるのですが、プログラマブルに取得したいニーズもありますよね。REST APIとGraphQL APIの両方で取得できるので、それぞれの方法をご紹介します。

[Tips] ドキュメンテーションの在処

APIの紹介の前に、GitHub Enterpriseに関するドキュメンテーションについて補足します。

GitHubのドキュメンテーションには「バージョン」があり、普段はデフォルトで設定されている「Free, Pro, & Team」が該当する場合が多く意識しないで閲覧できるのですが、GitHub Enterprise CloudやGitHub Enterprise Serverに関する情報を閲覧したい場合は明示的に「バージョン」を切替える必要があります。

ここでは「Enterprise Cloud」に切替えた状態でドキュメントを参照しています。

詳しくはこちらの記事で取り上げたのでご参考ください。

REST API

まず、REST APIでGitHub Enterpriseのライセンス利用状況を取得する方法です。GitHub REST APIの基本的な使い方は割愛します。

エンドポイントはこちらで、GETでアクセスします。{{ENTERPRISE_NAME}}は対象のエンタープライズの名前（スラグ）で置換えてください。Personal Access Tokenは、read:enterpriseのパーミッションが必要です。

エンドポイント

https://api.github.com/enterprises/{{ENTERPRISE_NAME}}/consumed-licenses

以下のようなレスポンスを得られます。

レスポンス例

{
  "total_seats_consumed": 52,
  "total_seats_purchased": 100,

詳しくは、下記のドキュメントの「List enterprise consumed licenses」をご参照ください。

GraphQL API

GraphQL APIでも同様に、GitHub Enterpriseのライセンス状況を取得できます。GraphQLの方が取得する項目を指定できるので、不要な項目を取得することなく、レスポンスのデータ量を抑えることができます。GitHub GraphQL APIの基本的な使い方は割愛します。

次のようなクエリでライセンスの利用状況を取得できます。変数例の{{ENTERPRISE_NAME}}は対象のエンタープライズの名前（スラグ）で置換えてください。

なお、GraphQL APIの場合、Personal Access Tokenのパーミッションはmanage_billing:enterpriseが必要です。

クエリ例

query($enterprise_slug:String!) {
  enterprise(slug: $enterprise_slug) {
    billingInfo {
      allLicensableUsersCount
      totalAvailableLicenses
      totalLicenses
    }
  }
}

変数例

{
  "enterprise_slug": "{{ENTERPRISE_NAME}}"
}

レスポンス例

{
  "data": {
    "enterprise": {
      "billingInfo": {
        "allLicensableUsersCount": 52,
        "totalAvailableLicenses": 48,
        "totalLicenses": 100
      }
    }
  }
}

GraphQLのEnterpriseオブジェクトに関しては次のドキュメントをご参照ください。

Epilogue

APIの利用自体は難しくないと思うのですが、GitHub Enterpriseの情報はドキュメントの「バージョン」を切り替えないと見つからないという罠があるので、見落としがちなので記事におこしてみました。