Zoomのライセンス総数と利用数をAPIから取得する


実現したい内容

この記事ではZoom APIを用いてライセンスの利用状況を取得する方法についてまとめます。
Zoomのライセンスはユーザ毎に付け替えすることが可能です。 その際に、そもそもライセンスの総数や割当状況を確認したいという要件があると思います。
そのAPIが存在しているか、どうやってAPIを叩いたら良いかという点で少しハマったためそこを記録しておきます。

Zoom API - API Reference - Zoom Developer - Technical Documentation and Reference

結論

  • APIコールのためのZoomアプリを作成する
  • Get plan APIをコールする

実現方法

実現したい要件は以下です。
- APIコールで購入済みのZoomのライセンス総数を取得したい - ライセンスの利用総数もあわせて取得したい

zoom number of licenses apiなどのキーワードで検索すると、以下のフォーラムの質問が見つかりました。 質問の内容としては実現したい内容と同じかと思います。

Is there a way see from the API how many remaining licenses I have in my account? - API and Webhooks - Zoom Developer Forum

その回答は以下でした。

You can call the GET Users endpoint 39 which includes the users plan type.

You can also call the Get Plan Usage endpoint 49 to get plan / billing related info.

GET Users endpointGet Plan Usage endpointを使えばできるとのことです。 Get Usersの方はユーザ一覧を取得して、全ユーザの属性を確認すれば良いという内容と思われたので、Get Plan Usage endpointの方を利用する方針としました。
当該のAPIのドキュメントは以下のリンクから確認できます。
Get plan usage - Billing - Zoom API - API Reference - Zoom Developer - Technical Documentation and Reference

APIコールのためのZoomアプリを作成する

まずZoomのAPIコールのために必要はZoomアプリを作成します。
Zoomアカウントにログインして、https://marketplace.zoom.us/develop/createから作成することがきます。
今回はOAuth2.0による認証を選択しました。 アプリの公開処理は必要な手続きが大変 + 内部のみ使うため publish this appのチェックは外しておきます。

OAuth2.0の設定は一般的なものと同様なため、この記事ではOAuth2.0の詳細な設定については省略します。 通常通りclient_d,client_secret, redirect_uriなどの設定を行ってください。

1点重要な部分はscopeの設定です。

ドキュメントによるとAPIコールのためには account:read:adminの権限が必要なため、このscopeは必須です。それ以外のscopeは不要です。

Get plan APIをコールする

Zoomアプリが作成できたためAPIコールしていきます。 今回はテストのため、PostmanでAPIの結果を確認していきます。

Postmanでリクエストを作成して、AuthorizationタブにOAuth2.0の設定をしていきます。 Callback URLを忘れずにアプリ側に設定することをしてください。 invalid redirect uriのエラーが出ます。
1点注意するのはZoomのAPIはトークン取得時のscope指定が不要なことです。 scopeを指定しても動作はしますが、指定したとしてもアプリ側に設定したscopeが使われるため無意味です。

Get New Access Tokenボタンをクリックするとトークンの取得が始まります。
Zoomの情報へのアクセスに対して許可を求められるので許可します。

成功するとAPIコールのためのトークンが取得できるため、APIをコールしていきます

ドキュメントによると/accounts/{accountId}/plans/usageがエンドポイントです。
accountId部分はテナントごとに異なります。本来このaccountIdを取得するためには、別のエンドポイントをコールした結果を確認する必要があります。

ただし、以下のような記載がありました。
> To get plan usage of a regular account, use the account:read:admin scope and provide “me” as the value of the accountId path parameter.

通常アカウントの情報を取りたい場合はaccountIdにmeを指定すれば良いとのことです。 逆に言うと、自分のaccountIdを取得して指定した場合はinvalid tokenでエラーとなってしまいます。(私の確認不足でしたがなかなかハマりました)

よって、コールするAPIは以下のようになります。
https://api.zoom.us/v2/accounts/me/plans/usage

これをコールすると以下のようなJSONが取得できます。
各属性のhostsが購入したライセンスの総数、 usageが利用している(ユーザに割当している)ライセンス数になります。

{
  "plan_base": {
    "type": "monthly",
    "hosts": 2,
    "usage": 1
  },
  "plan_zoom_rooms": {
    "type": "zroom_monthly",
    "hosts": 1,
    "usage": 0
  },
  "plan_webinar": [
    {
      "type": "webinar100_monthly",
      "hosts": 1,
      "usage": 1
    }
  ],
  "plan_large_meeting": [
    {
      "type": "large500_monthly",
      "hosts": 1,
      "usage": 1
    }
  ],
  "plan_recording": {
    "free_storage": "3 GB",
    "free_storage_usage": "0",
    "plan_storage": "0",
    "plan_storage_usage": "0",
    "plan_storage_exceed": "0"
  }
}

1点注意するのは、返ってくるJSONの属性の種類は各テナントによって異なることです。
購入しているライセンスの属性のみ結果に入ってくる形になります。
例えば、webinarライセンスを買っていない場合はplan_webinar等の属性はありません。

おわりに

今回はZoomのライセンス総数を取得するAPIについてまとめました。
情報がなかなか見つからなかった事とaccountIdの概念のせいで少しハマりました。 誰かのお役に立てば幸いです。

参考

Get notified on new marketing insights

Be the first to know about new B2B SaaS Marketing insights to build or refine your marketing function with the tools and knowledge of today’s industry.