こんにちは。CData Software Japanリードエンジニアの杉本です。
今回は今伸びに伸びているWeb会議サービス Zoom で提供されているAPIの使い方、OAuth 2.0 と JWT による認証方法といくつかのAPIのリクエスト方法を解説していきます。
なお、この記事ではChatbot としての使い方や Webhookは対象外です。
Zoom APIとは？
ビデオ会議サービス Zoom が提供する外部サービス連携用のAPIです。
ミーティングのデータを操作したり、ユーザーのデータを取得するための API を提供しています。
また、Marketplaceも提供されており、Google Calendar や Slack とAPI連携するアプリなどが公開されています。
API 基本情報
以下のリンクにAPIの基本的な情報が書かれています。
https://marketplace.zoom.us/docs/api-reference/zoom-api
この記事を書いている時点では、バージョンは2.0
Base URLは「https://api.zoom.us/v2」
Postmanに取り込んでみたところ、APIの数は「312 Requests」あるようです。多いですね！
ちなみに Zoom API は OAS （Open API Specification）で定義されているようです。
Postman にそのまま取り込むことができるので、API検証時にはこれを活用すると良いでしょう。
https://kageura.hatenadiary.jp/entry/postmancollection
注意したいこと
Zoom APIはかなり頻繁にアップデートされているみたいです。なので、ここに載っている情報も変わってしまう可能性が十分にあるので注意しましょう。
また ZoomAPIは通常のAPIとマスターアカウントAPIに分かれるようです。
マスターアカウント APIはあらかじめZoom ISVチームに連絡する必要があるので注意しましょう。いくらOAuthのScopeで要求が成功しても、ISVチームに受諾されていなければ、エラーが返ります。
例えば「List Sub Accounts」などがマスターアカウントAPI に該当します。
API の使い方（認証）
Zoom API の認証方法
OAuth 2.0 でアクセストークンを取得して行う方法とJWTを使う方法があります。
前者は基本的にはブラウザログインを要求し、ユーザーを特定して実行するアプリからAPIを使用する場合、後者はログインプロセスを用いないバッチ処理やデーモン用として使用する場合、と認識しておくといいと思います。
OAuth 2.0 によるアクセストークンの取得方法
Zoom API の OAuthは「Authorization Code Grant」と「Client Credentials Grant」がサポートされています。
ただ、後述しますが「Client Credentials Grant」はかなり利用範囲が狭いものなので、基本的には「Authorization Code Grant」を使うことになるでしょう。
今回は「Authorization Code Grant」を中心に解説していきます。
アプリの登録
それではまずアプリの登録を行いましょう。以下のURLにアクセスして、「Develop」から「Build App」をクリックします。（ちなみに事前にDeveloper登録をしておきましょう。）
https://marketplace.zoom.us/docs/guides/build/oauth-app
作成するアプリの種類の中から「OAuth」を選択します。
続いて作成するアプリの名前とアプリケーションタイプ、Zoom マーケットプレイスにアプリをリリースするかどうかの設定を入力します。今回は個人で利用するため、Marketplaceには公開しない設定としました。
アプリケーションタイプはOAuthでの認証時のユーザー範囲でデータを取得するのか（User-Managed app）、すべてのユーザーのデータにアクセスできるようにするか（Account-level app） の違いになります。
なお、Scopeは予めこのアプリ管理画面で登録したものが利用されます。よくAuthorize URLへのリクエスト時にScopeを指定するアプローチがありますが、Zoomの場合はその指定をしないので、注意しましょう。
アプリを作成すると、「App Credentials」でClientIDとClientSecretが取得できます。
また、合わせて OAuth の Code Grantでリダイレクト先となるURLを指定しておきます。今回はクライアントアプリケーションのPostmanから実行することを想定して、localhostを指定しました。
合わせてWhitelistにも対象となるURLを登録しておきます。基本的にはリダイレクト先URLのベースとなるURLを登録すると良いでしょう。詳しくはこちらを参照。
続いてアプリのアクセス範囲となるScopeの設定を行います。「Scopes」のタブに移動して「＋ Add Scopes」のボタンをクリックし
任意のScopeを追加できます。今回はユーザーデータのスコープを追加してみました。ここは用途に応じて、指定しましょう。
各APIで必要なScopeは各APIのリファレンスページに書かれています。
https://marketplace.zoom.us/docs/api-reference/zoom-api/users/users
Authorization Code Grant でアクセストークンを取得
それでは、登録したアプリを使ってアクセストークンを取得してみます。
https://marketplace.zoom.us/docs/guides/auth/oauth
Authorize URLとToken URLは以下のとおりです。
- Authorize URL：https://zoom.us/oauth/authorize
- Token URL：https://zoom.us/oauth/token
まず、Authorize URLの生成ですが、「response_type」にCodeを指定し、予め取得・登録しておいた「client_id」と「redirect_uri」を指定して、以下のようなURLを生成し、ブラウザで表示します。
https://zoom.us/oauth/authorize?response_type=code&client_id=icIViOPfRpWVdiACkt664A&redirect_uri=http://localhost:33333
ちなみに OAuthの場合、Scopeをクエリパラメータで指定するアプローチが多いですが、Zoomの場合はアプリに予め登録していたScopeで認可を行うようになっています。
認可が完了すると、以下のようなCallbackを受け取るので、
http://localhost:33333/?code=Fc08L7qy0p_ScaC1Pn4R6W4F41sp6V8pw
その後、このCodeを利用して、アクセストークンの取得リクエストを作成します。クエリパラメータで「grant_type=authorization_code」を指定し、「code」と「redirect_uri」に受け取ったcodeと登録していたリダイレクトURLを指定します。
ここでちょっと注意したいのが、Headerで「ClientId」と「ClientSecret」を組み合わせたBasic認証を指定する必要がある点です。「ClientId:ClientSecret」の値をBase64エンコードした値を「Authorization: Basic」ヘッダーに指定します。
POST /oauth/token?grant_type=authorization_code&code=Fc08L7qy0p_ScaC1Pn4R6W4F41sp6V8pw&redirect_uri=http://localhost:33333 HTTP/1.1 Host: zoom.us Authorization: Basic aWNJVmlPUGZScFdWZGlBQ2t0NjY0QTpENEllTUxkWG1XZk8xbExzbDcwNDB0eHlPTWFIU1VNZA==
Postmanでは以下の通り、指定できます。これでアクセストークンを取得できます。
ちなみに、Postmanの標準機能の OAuth 2.0 でも取得できます。
Grant Typeで「Authorization Code」を選択し、それぞれの項目に上記で指定した値を設定するだけです。特にOAuthのプロセスを意識することが無い場合は、こっちのほうが簡単です。
アクセストークンを取得したら「Authorization: Bearer」のヘッダーでアクセストークンを指定することで、APIリクエストを実行できます。
以下は List Users のリクエスト方法になります。
GET /v2/users HTTP/1.1 Host: api.zoom.us Authorization: Bearer eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI2YzZjNmI0MC04NzgyLTRhMzYtYjY0OC01YmZjZjU5NTNmNjcifQ.eyJ2ZXIiOjcsImF1aWQiOiI3NTk5ODQwNjAyOTJkMTA2MmYyODE2Y2ExYTYyYzcxMiIsImNvZGUiOiJHTTk2YTVCeEtjXzJldElIcE5wU1hHU0hpYWVmUU9LbkEiLCJpc3MiOiJ6bTpjaWQ6ZkFGcFJSdThTRnVodVVoVjBncjJxQSIsImdubyI6MCwidHlwZSI6MCwidGlkIjowLCJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ1aWQiOiIyZXRJSHBOcFNYR1NIaWFlZlFPS25BIiwibmJmIjoxNTk3NTg0OTE2LCJleHAiOjE1OTc1ODg1MTYsImlhdCI6MTU5NzU4NDkxNiwiYWlkIjoiY000UVMtRVdSM3VaV2FEVGFia1RiQSIsImp0aSI6IjMzZjcxNzYwLTA1NWUtNGYxZC05YzQ5LTI5NzdjYTNiZDE5ZSJ9.kyIP8lzv2hr8kX0V8IpXz0xnj5y0TmdnVxv5qIHxRP_Th_fdsDySLPZTkMvEe3pIXAqa7USTAMLucj74IZQsCg
Client Credentials Grant でアクセストークンを取得
Client Credentialsはユーザーの許可を必要としない Access Tokenの取得方法です。
注意したいのは、このClient Credentialsで取得したAccess Tokenが使用できるAPIは「POST /im/chat/messages」だけ、という点ですね。
https://marketplace.zoom.us/docs/api-reference/zoom-api/chatbot-messages/sendchatbot
以下のようにToken URLに対して、「grant_type=client_credentials 」を指定し、Basic認証でClientIdとClientSecretを指定することで、アクセストークンが取得できます。
POST /oauth/token?grant_type=client_credentials HTTP/1.1 Host: zoom.us Authorization: Basic aWNJVmlPUGZScFdWZGlBQ2t0NjY0QTpENEllTUxkWG1XZk8xbExzbDcwNDB0eHlPTWFIU1VNZA==
JWTによる認証方法
最初に JWT用のアプリを作成します。OAuthの時と同じ様にアプリ作成の画面に移動して「JWT」を選択し任意の名前で作成します。
https://marketplace.zoom.us/docs/guides/auth/oauth
作成後、以下のような画面に移るので必要な項目を埋めましょう。なお、JWTで作成したアプリは必ず「Account-level app」となり、Scopeはすべて備えるようです。
JWTの生成
JWTの生成にはAPI Keyと API Secretという値を利用します。生成方法は以下のURLで参照できます。
なお、期限付きのJWTを画面上から生成できるので、今回はこれを利用します。
生成した JWT Tokenは OAuthで取得するアクセストークンと同じ様に使用できます。
以下はユーザーを取得する時のリクエスト例です。 Authorization: Bearer でJWT Tokenを指定してください。
GET /v2/users HTTP/1.1 Host: api.zoom.us Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOm51bGwsImlzcyI6Il85ZVllNkREU3NTZi1ReGpBOEZINVEiLCJleHAiOjE1OTc1ODk4MzEsImlhdCI6MTU5NzU4NDQzM30.jGhuczq-HsXnFy6_r2I5wTEA1E8eEnISNOsGwx4Y-cI
API の使い方（各種データの取得）
それではいくつか具体的なデータの取得方法を紹介したいと思います。
ミーティングの取得
まずは以下のようなミーティング一覧を取得してみます。必要なScopeは「meeting:read:admin meeting:read」です。
ミーティングの取得で少し注意したいのは、主催者となる Userを指定してリクエストをする必要があるという点です。
なので、必ずミーティングを取得したい対象のユーザー：主催者を取得してから「GET users/:userId/meetings」でリクエストを行いましょう。
GET /v2/users/2etIHpNpSXGSHiaefQOKnA/meetings HTTP/1.1 Host: api.zoom.us Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOm51bGwsImlzcyI6Il85ZVllNkREU3NTZi1ReGpBOEZINVEiLCJleHAiOjE1OTc1ODk4MzEsImlhdCI6MTU5NzU4NDQzM30.jGhuczq-HsXnFy6_r2I5wTEA1E8eEnISNOsGwx4Y-cI
これで以下のようにデータが取得できます。
開催後のミーティングデータの取得
もう一つミーティングデータとして、過去に開催したミーティングデータを取得してみたいと思います。
ここでは「Get Past Meeting Details」を使うのですが、このレスポンスには「ミーティングにかかった時間」や「参加者数」が取れるのが特徴です。
リクエストには「/past_meetings/:meetingId」で取得したいMeetingIdを指定して、実行します。
GET /v2/past_meetings/343242342342 HTTP/1.1 Host: api.zoom.us Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOm51bGwsImlzcyI6Il85ZVllNkREU3NTZi1ReGpBOEZINVEiLCJleHAiOjE1OTc1ODk4MzEsImlhdCI6MTU5NzU4NDQzM30.jGhuczq-HsXnFy6_r2I5wTEA1E8eEnISNOsGwx4Y-cI
CData API Driver での使い方
最後に CData API Driver で Zoom API Profile を使うための設定方法を紹介します。
https://www.cdata.com/jp/apidriver/
CData API Driver で Zoom APIを使う場合は、使用したいテクノロジーのAPI Driverと
https://www.cdata.com/jp/apidriver/download/
Zoom API Profileを予めダウンロードしておきましょう。
OAuth 場合の設定方法
CData ODBC API Driver の場合は以下のように指定します。
- Profile：ダウンロードしたZoom API Profileを指定します。例：C:\Zoom.apip
- Callback URL：リダイレクトURLを指定します。例：http://localhost:33333
- Initiate OAuth：GETANDREFRESHを指定します。
- OAuth ClientId：作成したアプリのClientIdを指定します。例：fAFpRRu8SFuhuUhV0gr2qA
- OAuth Client Secret：作成したアプリのClient Secret を指定します。例：pROkr52DgDObsY6fZTVmlZ22uPxaLg27
接続テストをクリックすると、ブラウザでログイン画面が立ち上がるので、ログインおよび承認を実行することで接続が完了します。
JDBCの場合は以下のように接続文字列を指定します。
jdbc:apis:Profile=C:\Zoom.apip;InitiateOAuth=GETANDREFRESH;OAuthClientId=fAFpRRu8SFuhuUhV0gr2qA;OAuthClientSecret=pROkr52DgDObsY6fZTVmlZ22uPxaLg27;CallbackURL=http://localhost:33333;
JWTの場合の設定方法
JWTでアプリを作っていた場合は、以下のように設定することでJWT Tokenによるアクセスが可能です。なお、CData Driver 自身でJWTは生成できないので、予めUIから生成したJWT を指定してください。
- Profile：ダウンロードしたZoom API Profileを指定します。例：C:\Zoom.apip
- Callback URL：任意のリダイレクトURLを指定します。プロパティの仕様上必須ですが、値はなんでもかまいません。例：http://localhost:33333
- Initiate OAuth：OFFを指定します。
- OAuth ClientId：作成したJWT アプリのClientIdを指定します。例：_9eYe6DDSsSf-QxjA8FH5Q
- OAuth Client Secret：作成したJWT アプリのClient Secret を指定します。例：nJc2T8H062jMR1YleT82dO5QoBF7pA0YXaJJ
- Other：生成したJWT Tokenを指定します。例：OAuthAccessToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOm51bGwsImlzcyI6Il85ZVllNkREU3NTZi1ReGpBOEZINVEiLCJleHAiOjE1OTc1OTQ3ODgsImlhdCI6MTU5NzU4OTM5MH0.hBpM2yIv6biXkCg03l8pmOi_pdfdxgJ2TWKt60OCqy0;
JDBCの場合は以下のように指定できます。
jdbc:apis:Profile=C:\Zoom.apip;OAuthAccessToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOm51bGwsImlzcyI6IjJaWEFZMHM1VGJLYWF2RjNOODh6ZXciLCJleHAiOjE2Mjg5NTMyMDAsImlhdCI6MTU5NzQ5MTQyMn0.qm7V7YCIpr7ue6--u8BM6pMmZTU8YauvtXjxcBdeTtM;OAuthClientId=_9eYe6DDSsSf-QxjA8FH5Q;OAuthClientSecret=nJc2T8H062jMR1YleT82dO5QoBF7pA0YXaJJ;CallBackURL=http://localhost:33333;
CData Driverでの接続例
実際に CData Driverを使った接続例として、Power BI Desktopを使った方法を記事にしてみました。是非参考にしてみてください。
