Zoom APIへお試しリクエストを送る方法 (JWT・OAuth)

XTechグループ Advent Calendar 2020の7日目は、エキサイト株式会社 エンジニアの@aharenchiがお送りします。

はじめに

オンライン会議やオンライン授業、オンライン飲み会など、人とのコミュニケーションはオンライン上が多くなってきました。
そんなオンラインコミュニケーションを楽しくするアプリを開発できるのだったらやってみたいと思うでしょう。
オンライン会議サービスのZoomでは無料でAPIを提供しており、APIを利用してMeetingの作成、ユーザ情報の作成、取得等様々なことを行うことが可能です。

「Zoom APIを使って面白いアプリを開発したい〜」と思い、次にZoom APIリファレンスページを閲覧すると、ドキュメントと「Send a Test Request」と書かれたツールを見つけるでしょう。

「Send a Test Request」では、Zoom APIにリクエストを実際に送信できミーティングの作成等ができます。
つまり、Zoom APIのリファレンスページ内でドキュメントを読む事とAPIの機能の応答を確認する事の両方ができるのです。便利ですね。

そこで今回は、Zoom APIをすぐに試せるようになることを目的に、ZoomのAPI認可の種類と、リファレンスページ内の「Send a Test Request」の使い方について説明します。

Zoom APIの利用準備

Zoomアカウント登録とアプリを作成する必要があります。

Zoomの公式サイトでZoomアカウントを新規作成してください。
すでにアカウントがある方はZoomアカウントでログインし、Zoom Developer Platformにアクセスしてください。

Create an Appというボタンがあるのでクリックしてアプリを作成します。
Create Appページでは、アプリの種類を選択することができます。
Zoom APIを利用する場合は、JWTとOAuthどちらかを選択します。

Zoom APIの認可について

JWTとOAuthとはZoom APIの認可の種類です。
認可とは、Zoom APIがAPI利用者に該当ユーザのZoom情報を操作する権限(例：ユーザの代わりにmeeting作成する権限/ユーザ情報を取得する権限)があるかを確認することです。

では、JWTとOAuthについてざっくり説明します。

JWT

アプリ作成時に発行されるAPI KeyとAPI Secretという鍵を使って認可を受けます。
操作できるZoomの情報は、そのアプリを作成したアカウントに所属するユーザの情報のみです。
Zoomでは1つのアカウントに複数のユーザを作成することができるのですが、そのアカウントに属するユーザの情報は操作することができます。
アプリを作成したアカウント以外のユーザに関してはZoom APIから操作できません。
個人用や1つの会社アカウントに属するユーザアカウントが利用するアプリをつくる場合は、JWTを選択するといいでしょう。

OAuth

ユーザにブラウザログインしてもらい、Zoomの情報を操作することを認可してもらうことで実現します。
操作できるZoomの情報は、ブウザログインして認可をしたユーザの情報です。
不特定多数のZoomアカウントが利用するアプリをつくる場合は、OAuthを選択するといいでしょう。

ざっくりJWTとOAuthについて分かったと思いますので、次はそれぞれのアプリの作成手順とTest Requestを実行する方法を説明します。

JWTでのアプリ作成とTest Requestを実行する方法

JWT認可アプリを作成し、Zoom APIを利用してミーティング作成までを行います。

1. アプリ作成ページで、JWTを選択

アプリ作成ページで、JWTを選択します。

2. 必要な情報を記入

以下の情報が入力必須なので記入していきます。

• アプリ名
• 会社名
• 開発者名
• 開発者のメールアドレス

3. App Credentialsページのデータを参照

通常は、API KeyとAPI Secretを使ってJWT Tokenを生成し認可を行いますが、すでに生成されたJWT Tokenも表示されています。
今回はすぐに試すことが目的なので、生成済みのJWT Tokenを使います。( ※ このJWT Tokenは本番アプリでは使用しないでください。)
API KeyとAPI Secretを使ったJWT Tokenを生成方法はZoomドキュメントを参照ください。

4. Feature設定

Webhook通知を設定することができます。今回は設定しません。

5. Activation設定

アプリがアクティブになってることを確認できたら、App作成終了です。

6. Zoomミーティング作成

今回は、エンドポイント「/users/{userId}/meetings」を使って、インスタントミーティングを作成します。
「/users/{userId}/meetings」のページにアクセスし、oauth_access_tokenにJWT Token、userIdにZoomアカウントのメールアドレスを記入します。Bodyにはミーティングの種類をインスタントとして記入します。

Sendボタンをクリックするとレスポンスが返ってきます。レスポンスの中身にZoomURLが含まれており、そのURLにアクセスするとZoomミーティングを開始することができます！Zoomミーティング作成完了です！ぱちぱち👏

OAuthでのアプリ作成とTest Requestを実行する方法

OAuth認可アプリを作成し、Zoom APIを利用してミーティング作成までを行います。

1. アプリ作成ページで、OAuthを選択

アプリ作成ページで、OAuthを選択します。

2. OAuthアプリの設定

「Choose app type」ではZoom情報のアクセス範囲を設定できます。エンドポイントごとに、「Account-level app」か「User-managed app」か決まっているのでそれを確認して設定しましょう。「/users/{userId}/meetings」は「Account-level app」である必要があるので、それを設定します。

作成したアプリはマーケットプレイスに公開することができます。今回はお試し実行なので、公開設定はOFFにします。

3.リダイレクトURL、ホワイトリストURLを設定

通常はOAuthアクセストークンを受け取るURLを作成し、そのURLをリダイレクトURLとホワイトリストURLに設定します。今回はリファレンスページ内で実行するので、ZoomのURLを設定します。

App Credentialsページに記載されているClient IDとClient SecretはOAuthトークンを生成するために使います。今回はリファレンスページ内の「Send a Test Request」に貼り付けて使います。詳しいやり方はあとで説明します。

4. 必要な情報を記入

以下の情報が入力必須なので記入していきます。

• アプリの短い説明
• アプリの説明詳細
• 開発者の名前
• 開発者の連絡

5. Feature設定

Webhook通知を設定することができます。今回は設定しません。

6. OAuth認可によってアクセスできる権限を設定

「+ Add Scopes」ボタンをクリックし、アクセス権限を設定しています。今回はミーティング作成をするので、ミーティングに関するアクセス権限を設定します。

7. Activation設定

アプリがアクティブになってることを確認できたら、App作成終了です。

8. Zoomミーティング作成

今回は、エンドポイント「/users/{userId}/meetings」を使って、インスタントミーティングを作成します。
「/users/{userId}/meetings」のページにアクセスし、「Get Access Token」をクリックします。

クリック後、下記の画像のようなモーダルが出てきます。App Credentialsページに記載されていたClient IDとClient Secretを記入して「Get Access Token」をクリックします。

そうすると新しいページが開き、認可を求めてくるのでクリックします。

認可をしてリファレンスページに戻ると、oauth_access_tokenにOAuthアクセストークンが記入された状態になっています。
userIdにZoomアカウントのメールアドレス、Bodyにはミーティングの種類をインスタントとして記入します。

Sendボタンをクリックするとレスポンスが返ってきます。レスポンスの中身にZoomURLが含まれており、そのURLにアクセスするとZoomミーティングを開始することができます！Zoomミーティング作成完了です！ぱちぱち👏

コード実装方法を知りたい方へ

今回はZoom APIリファレンスページ内にあるツールでの認可、実行方法について説明しました。
Zoom API認可・実行をコードで実装する方法を知りたい方は、それぞれサンプルコードが公式で用意されていますのでそちらをご覧ください。

OAut認可の実装方法
https://github.com/zoom/zoom-oauth-sample-app

JWT認可の実装方法
https://github.com/zoom/zoom-api-jwt

おわりに

私がZoom APIを試しに利用する際に、どちらの認可を選んだほうがいいか悩んだり、すぐに試せるリファレンスページ内のテストツールの使い方を理解したのが時間をかけてドキュメントの読み込みをしたりコードを書いた後だったのでもっと早めに知りたかったと思いがあり、今回の記事を作成しました。

Zoom APIをこれから利用してみる方のお役に少しでもなれたらと思います。

XTechグループのアドベントカレンダーはまだまだ続きます。
明日の執筆担当は@ebi_さんです。引き続きお楽しみください。

採用情報はこちら↓
https://www.wantedly.com/companies/excite

参考文献

https://marketplace.zoom.us/docs/api-reference/using-zoom-apis
https://marketplace.zoom.us/docs/api-reference/testing-zoom-apis
https://www.cdatablog.jp/entry/2020/08/17/085924