~Master account APIs について~

~https://marketplace.zoom.us/docs/api-reference/master-account-apis~ ~https://www.cdatablog.jp/entry/2020/08/17/085924#注意したいこと~

~マスターアカウントapiを使うには、あらかじめzoom営業に連絡しておく必要がある？~ ~ユーザーリストの取得はマスターアカウントapiではないので、連絡は不要かも。~

jwt認証

apiにアクセスするにはトークンが必要で、トークンはapiキーと任意の有効期限から生成できる。本番ではトークンを都度生成する運用となるため、apiキーは機密情報となる。 ~apiシークレットはjwt認証では使われてない？~ 必要だった。

バッチ処理全体の冒頭で生成したトークンを使いまわしたいところだが、動画ファイルのダウンロードにもトークンが必要になり、ファイルサイズを考えると相応に時間がかかると予想されるため、apiアクセスの都度トークンを生成するほうがよさそう。

バッチ処理の流れ

以下の環境変数を確認する
- ZOOM_API_KEY
- ZOOM_API_SECRET
- ZOOM_IMPORT_INTERVAL
- ZOOM_IMPORT_TO
- ZOOM_IMPORT_WOWZA_BASE_URL
- 未設定または空文字などの明らかに不正な値の場合は、バッチを終了する
zoomサブアカウントのリスト、またはユーザーリストを取得 GET /accounts または GET /users
- メールアドレスがchibichilo側にあるか確認する
- ない場合はスキップ
- ユーザごとのインポートon/offの設定を確認する
- user.settings.zoom_import.enabled
- offの場合はスキップ
- クラウドレコーディングから過去のミーティングを取得 GET /users/{userId}/recordings
- ミーティングidが一致するresourceがあるか確認する
  - ある場合はスキップ
- file_type=MP4のファイルをダウンロードするダウンロードurlにはアクセストークンが必要。jwtでもoauthでもよさそう動画の種類がいくつかあるため、以下の種類の上から順に探して最初に見つかったものをダウンロード
  - shared_screen_with_speaker_view(CC)
  - shared_screen_with_speaker_view
  - speaker_view
  - shared_screen_with_gallery_view
  - gallery_view
  - shared_screen
- ~file_type=TRANSCRIPTのファイルがあれば、ダウンロードして内容をvideo.tracksに追加~ 今はやらない
- ~file_type=CCのファイルがあれば、ダウンロードして内容をvideo.tracksに追加~ 今はやらない
- 環境変数 ZOOM_IMPORT_TO で指定したサイトに動画ファイルをアップロードする。(現在wowzaのみ対応)
- ミーティングの詳細情報を取得する GET /meetings/{meetingId}
- ダウンロードしたファイルでresource, video, topicを作成する resource.importedid = "zoom" + meeting.id topic.name = "📹 " + meeting.topic topic.description = meeting_detail.agenda topic.timeRequired = meeting.duration topic.createdAt = meeting.start_time zoomからインポートしたフラグをどうするかは仕様待ち
- 環境変数 ZOOM_IMPORT_AUTODELETE が設定されてるか確認する
  - 設定されてる場合は、ミーティングをゴミ箱に入れる DELETE /meetings/{meetingId}/recordings

※リストを取得するapiはいずれもページングに関するパラメータが必要で、一回のリクエストですべてのデータが取れるとは限らない。

バッチの自動実行について

node-cronかnode-scheduleでできそう。どちらもcronと同じ書式でスケジュールを設定可能。要件としては1日1回実行ではあるが、昼に1時間や2時間おきに実行するなどの設定もアリか。運用はさまざまだと思われるため、環境変数から設定できるのが望ましい。また、スケジューラはサーバープロセス内で動作できるのが望ましい。個別の起動コマンドやスクリプトなどは不要にして、サーバ起動と同時にスケジューラも動き始めるようにしたい。

uiの変更

ユーザーログイン時の処理

以下の環境変数を確認する
- ZOOM_API_KEY
- ZOOM_API_SECRET
- ZOOM_IMPORT_INTERVAL
- ZOOM_IMPORT_TO
- ZOOM_IMPORT_WOWZA_BASE_URL
- すべて設定されてる場合は、zoomインポートをonにするか通知する
- onにする場合、設定画面に誘導する

ユーザー設定画面

zoomインポートのon/off設定
この画面はおそらく新設

環境変数の追加

ZOOM_API_KEY=xxxxxxxxxxxxxxxxxx
ZOOM_API_SECRET=xxxxxxxxxxxxxxxxxx
ZOOM_IMPORT_INTERVAL="1 6 * * *"
ZOOM_IMPORT_TO=wowza
ZOOM_IMPORT_WOWZA_BASE_URL=http://localhost:8080
ZOOM_IMPORT_AUTODELETE=1

db定義の変更

ALTER TABLE "users" ADD COLUMN "email" TEXT NOT NULL DEFAULT E'';
CREATE INDEX "email" ON "users"("email");
ALTER TABLE "users" ADD COLUMN "settings" JSONB NOT NULL DEFAULT '{}'::JSONB;
ALTER TABLE "resources" ADD COLUMN "imported_id" TEXT NOT NULL DEFAULT E'';
CREATE INDEX "imported_id" ON "resources"("imported_id");

参考資料

Zoom API - API Reference - Zoom Developer - Technical Documentation and Reference https://marketplace.zoom.us/docs/api-reference/zoom-api

Master account APIs - API Reference - Zoom Developer - Technical Documentation and Reference https://marketplace.zoom.us/docs/api-reference/master-account-apis

クラウドレコーディング – Zoom ヘルプセンター https://support.zoom.us/hc/ja/articles/203741855-Cloud-Recording

記録管理 – Zoom ヘルプセンター https://support.zoom.us/hc/ja/articles/205347605

Zoom APIを試してみる JWT編 https://qiita.com/nanbuwks/items/ed74a76a0f294c0bf4ed

ZoomのAPIを使ってみた - Qiita https://qiita.com/akihiko_sugiyama/items/806e69dabc41c90677bc

Zoom APIの使い方：OAuth・JWT による認証方法・Postman での実行方法 - CData Software Blog https://www.cdatablog.jp/entry/2020/08/17/085924

Zoomの録画データをダウンロードする - 芝浦工業大学　学術情報センター https://web.sic.shibaura-it.ac.jp/Rec_data_download

Node.jsで定期実行メモ - Qiita https://qiita.com/n0bisuke/items/66abf6ca1c12f495aa04

Node-Schedule で cron ライクなスケジュールジョブを実現する : まだプログラマーですが何か？ http://dotnsf.blog.jp/archives/1077733140.html

認証方法について

oauthはシンプルだが画面遷移が発生するため、reactとの相性は良くないかもしれない。
jwtのほうが合いそうだが、この方法はまだ試したことがない。まずはこちらで実装してみる。

クラウドレコーディングについて

初期状態だとストレージ容量がかなり少ない。1gbまたは0.5gb 基本的には課金前提か、録画即chibichiloインポートして消すかのどちらか？
zoomの管理画面から録画データのダウンロードはできるようなので、同じことをapiでやることになるはず https://web.sic.shibaura-it.ac.jp/Rec_data_download

一日一回のバッチ処理で、録画データを一括で取り込み、resourceだけ先に作成する。
- このとき使うzoomアカウントは、教員各自のアカウントではなく、組織アカウント。
教員が教材を作る時に、インポート済みのresourceを選択するだけ。都度インポートはしない。

Internal Meeting メモ (as is)

処理の流れ

自動バッチで zoom 管理者権限貰って取ってくる
各 meeting の主催者メールアドレスを取得する
対応する LTI / CC ユーザを見つける
そのユーザの Topic として登録する
動画を Wowza に UP する
Zoom から動画を削除 (ゴミ箱に移動)

確認事項

Vimeo 対応などを行って複数 VOD 対応した場合に Zoom import はいずれか一つに決め打ちなのか、ユーザ毎の設定に対応するのか
- Zoom import はバッチ処理なので、ユーザ毎に選択させるなら事前に決めさせておかなければならない
メールアドレス対応は Zoom 録画 import 時点での都度対応だけでいずれかのアドレスの変更への追従などは行わない
「制限事項（開発概要B）が行われない」の前半が日本語になっていない
- メールアドレス対応がない場合とか変更があった場合のこと？インポート時に存在するメールアドレスにのみ割り当てて他は放置でいいのでは？
- 後半は Wowza 動画は Zoom import に限らず制限できないだけの話
LTI 連携のアドレス登録について
- 「CHiBi-CHiLOのユーザーテーブルにはメールアドレスをもうける」を実装・導入
- 一度以上 LTI から該当ユーザがログインして貰う必要がある
- その後に録画した Zoom 動画を自動インポート
対応付けられた CC ユーザ以外の動画の扱いは？
- 対応付けられた CC ユーザのある動画だけをインポートで良いか？
- 未ログインユーザは一度ログインしたら一括インポートできる
- LTI ログインしたら勝手に既存の全 Zoom 動画をインポート・削除して良いのか？
- ログイン時にユーザに対して通知・承認を得るか？「この CC では Zoom 空のインポート機能が有効化されています、自動的に user@example.com で録画した Zoom の動画を全てインポート・Wowza にアップロード・Zoom 空削除してよろしいですか？」という確認をして OK だったらオンにするか？
- Zoom から削除はしないがインポートはする場合にインポート済動画の識別をどうするか。それをするならインポート済動画リストを保持する必要はある。但し無限に増えるインポート済リストを保持し続けたくない。インポート対象を直近 x ヶ月とかに絞るか？

実装検討

「Zoom録画で作成したトピックはそれがわかるようにアイコン等つける」の実装方法
- 見た目で目立たせる
- アイコン付けるなら Topic のデータとしてフィールドを追加するか JSON の中にフラグを立てる必要がある。フィールド追加ならトピックの検索での絞り込みもありえるがどうしたいのか
  - 同じ問題は PPT audio 動画のインポートにもあったので、どうせやるならそっちもフラグ立てて同じ対応をすべき (沢山フィールド追加していくことになるのは嫌じゃない？大丈夫？)
- トピックタイトルの Prefix 文字列 (絵文字例えば :ビデオカメラ: 📹) で目立たせる (フィールド追加など DB 影響なし)
- 単純に日付的に目立たせる
- 更新日時を現時刻でインポートすることで分かり易くする (Zoom の録画日付を無視してインポートするかどうか？)
「トピック一覧画面で，トピックを選択してブックを作成できるようにする」
- トピック一覧画面に「トピックを選択してブックを作成」ボタンを付けてクリックしたらトピック選択モード (ページ) に以降。選択後に「ブックを作成する」ボタンを押すとブック作成され、その編集ページに移行。
Zoom 動画削除後にゴミ箱から復活させられた場合問題
- Resource Object 側にインポート元の Zoom 動画 ID を入れるか？
zoom 動画インポート時の絞り込み処理
- ゴミ箱内ではない動画リストを取得
- メールアドレスをリストして CC ユーザと突き合わせ、該当するものだけ選択
- 更にインポート済動画を除外
- 残ったものだけインポート処理を行う
複数のLMSからのCHiBi-CHiLOにアクセスした場合のユーザー突き合わせへの応用
- これは Zoom 対応の要件外だと思うがコメント
- 久野さんの方で Link Object 作る話に関連するので事前共有 (メールアドレスフィールドは追加すること)
- 既存メールアドレスリストと付き合わせることで、既存ユーザがいたら紐付け、いなければ新規作成の流れが出来る
- 但し、ユーザが LMS の情報を保持している場合はそれを複数 LSM のデータを入れられる配列にするのか別テーブル(したくない)にするのか何かの対応が必要

開発スケジュール

7 月 (下調べ・詳細設計完了)
- LTI リンクからのメアド取得、記録に関しての確認
8 月 (import 基礎)
- Zoom API を使った各データの取得 (7月中に一部先行調査)
- Wowza UP までの流れを確認
- RO, TO 作成
9 月 (突き合わせ系)
- メールアドレス突き合わせ、絞り込み
- インポート済動画リストの作成
- 重複なく新規のみインポート
10 月 (本隊以外のUIサポート系)
- Zoom インポート動画を区別しやすく (検索絞り込みも？)
- トピック一覧からブック作成

「トピック一覧画面で，トピックを選択してブックを作成できるようにする」トピック一覧画面に「トピックを選択してブックを作成」ボタンを付けてクリックしたらトピック選択モード (ページ) に以降。選択後に「ブックを作成する」ボタンを押すとブック作成され、その編集ページに移行。

一覧画面で複数選択の概念を導入するという点は #411 に関連しています(#411 のissueを切り分けたほうがよさそう)

470 に分離しました

処理の流れ

* 自動バッチで zoom 管理者権限貰って取ってくる
* 各 meeting の主催者メールアドレスを取得する
* 対応する LTI / CC ユーザを見つける
* そのユーザの Topic として登録する
* 動画を Wowza に UP する
* Zoom から動画を削除 (ゴミ箱に移動)

確認事項

* Vimeo 対応などを行って複数 VOD 対応した場合に Zoom import はいずれか一つに決め打ちなのか、ユーザ毎の設定に対応するのか
  * Zoom import はバッチ処理なので、ユーザ毎に選択させるなら事前に決めさせておかなければならない

管理者がインポート先を決めておく。(ユーザごとは将来的な話)

* メールアドレス対応は Zoom 録画 import 時点での都度対応だけでいずれかのアドレスの変更への追従などは行わない

対応しない

* 「制限事項（開発概要B）が行われない」の前半が日本語になっていない
  * メールアドレス対応がない場合とか変更があった場合のこと？インポート時に存在するメールアドレスにのみ割り当てて他は放置でいいのでは？
  * 後半は Wowza 動画は Zoom import に限らず制限できないだけの話

更新していただく

* LTI 連携のアドレス登録について
  * 「CHiBi-CHiLOのユーザーテーブルにはメールアドレスをもうける」を実装・導入
  * 一度以上 LTI から該当ユーザがログインして貰う必要がある
  * その後に録画した Zoom 動画を自動インポート

これでOK

* 対応付けられた CC ユーザ以外の動画の扱いは？
  * 対応付けられた CC ユーザのある動画だけをインポートで良いか？
  * 未ログインユーザは一度ログインしたら一括インポートできる
    * LTI ログインしたら勝手に既存の全 Zoom 動画をインポート・削除して良いのか？
    * ログイン時にユーザに対して通知・承認を得るか？「この CC では Zoom 空のインポート機能が有効化されています、自動的に [user@example.com](mailto:user@example.com) で録画した Zoom の動画を全てインポート・Wowza にアップロード・Zoom 空削除してよろしいですか？」という確認をして OK だったらオンにするか？
    * Zoom から削除はしないがインポートはする場合にインポート済動画の識別をどうするか。それをするならインポート済動画リストを保持する必要はある。但し無限に増えるインポート済リストを保持し続けたくない。インポート対象を直近 x ヶ月とかに絞るか？

確認する必要はない。自動で全部やる。自動削除しないはありかもしれない。熊大に確認直近インポートnか月は管理側で設定する。熊大に確認

実装検討

* 「Zoom録画で作成したトピックはそれがわかるようにアイコン等つける」の実装方法
  * 見た目で目立たせる
    * アイコン付けるなら Topic のデータとしてフィールドを追加するか JSON の中にフラグを立てる必要がある。フィールド追加ならトピックの検索での絞り込みもありえるがどうしたいのか
      * 同じ問題は PPT audio 動画のインポートにもあったので、どうせやるならそっちもフラグ立てて同じ対応をすべき (沢山フィールド追加していくことになるのは嫌じゃない？大丈夫？)
    * トピックタイトルの Prefix 文字列 (絵文字 例えば :ビデオカメラ: 📹)  で目立たせる (フィールド追加など DB 影響なし)
  * 単純に日付的に目立たせる
    * 更新日時を現時刻でインポートすることで分かり易くする (Zoom の録画日付を無視してインポートするかどうか？)

何百もコンテンツがあって管理が大変。仕様待ち。

* 「トピック一覧画面で，トピックを選択してブックを作成できるようにする」
  * トピック一覧画面に「トピックを選択してブックを作成」ボタンを付けてクリックしたらトピック選択モード (ページ) に以降。選択後に「ブックを作成する」ボタンを押すとブック作成され、その編集ページに移行。

これでOK

* Zoom 動画削除後にゴミ箱から復活させられた場合問題
  * Resource Object 側にインポート元の Zoom 動画 ID を入れるか？

やはりインポート済みリストは必要

* zoom 動画インポート時の絞り込み処理
  * ゴミ箱内ではない動画リストを取得
  * メールアドレスをリストして CC ユーザと突き合わせ、該当するものだけ選択
  * 更にインポート済動画を除外
  * 残ったものだけインポート処理を行う

* 複数のLMSからのCHiBi-CHiLOにアクセスした場合のユーザー突き合わせへの応用
  * これは Zoom 対応の要件外だと思うがコメント
  * 久野さんの方で Link Object 作る話に関連するので事前共有 (メールアドレスフィールドは追加すること)
  * 既存メールアドレスリストと付き合わせることで、既存ユーザがいたら紐付け、いなければ新規作成の流れが出来る
  * 但し、ユーザが LMS の情報を保持している場合はそれを複数 LSM のデータを入れられる配列にするのか別テーブル(したくない)にするのか何かの対応が必要

マスターアカウントapiの制約を解除しないことには話が進みそうにないので、次のミーティングで開発に使えるzoom管理者アカウントを相談する。

打ち合わせで確認したこと (に少し勝手に追記した) メモ:

ユーザが CC ログインするまで Zoom インポートが出来ないのは OK
Zoom インポートのオンオフ
- Zoom インポート機能のオンオフはユーザ単位で制御可能にしたい (勝手にインポート、削除すると困ったことになるだろうしプライバシー問題などもありそうなので)
- CC が Zoom インポートをオンにして以降、ユーザが初回ログインする時にオンにするかどうかの確認を表示する
- ユーザがオンにする設定をしたら次のバッチ処理タイミングでインポートする
Zoom インポート後の動画削除オンオフ
- これはシステム単位で決まった挙動 (インポート後は常に削除) を想定
- 必要があればユーザ単位で削除のオンオフが出来ても良いのかもだがひとまずシステム単位で進める (そうしないと動画が残ってるのを減らしたいという大学側の希望が叶わない)
インポート対象の動画の種類は file_type = shared_screen_with_speaker_view || speaker_view のように優先順位上位のモノを 1 つ決め打ちでインポート
- ユーザ毎にインポートする動画の種類を選ぶ方法は提供しない
- ユーザが個別の録画毎にインポートする動画の種類を選ぶような方法も提供しない
インポート動画の区別とお知らせについて
- zoom インポートしたことを示すフラグは keyword の値として入れておく
- 検索システムでそれを使うのは後日の(日々実装する作業の)課題として今回の要件外
- 取りあえずトピック名の冒頭に Prefix 文字列 (絵文字例えば :ビデオカメラ: 📹) 付けて区別可能にする
- CC ログイン時に前回ログインからの自動インポート動画リストを通知したりすると便利かも知れないが今回は実装しない (そもそも CC システム全体として通知・お知らせ機能を作ってからの方が良いとも思ってる)
字幕対応については出来ることを議論したが今回は実装しない
- zoom の機能を使って英語の字幕は付与可能。それをインポートするのは可能なので予算確保してくれたら実装しましょう
- zoom が英語以外の字幕に対応したら他の言語も可能。それを待たずに実装するなら GCP/AWS などの API 使って字幕生成するというのを実装することが可能。
データ量について
- バッチ処理でダウンロードが間に合わないほど大量の動画が増え続けることはない、そういう場合のためのスケール対応実装までは考えない
- インポートをオンにした CC ユーザの分しかインポートしないので大学での Zoom 利用量が大きくともインポート対象は絞られる想定
- 大量の教員が同時に CC 初回ログインんして溜め込んだ動画を一気にインポートすることになったら困るが、そういう場合はバッチ間隔を一時的に長くするとかすれば平気じゃないか

今後について

TIES Zoom の権限貰って API 調査/テスト/設計する (今週)
帝塚山の Zoom 権限貰って実践的なデータ・ユーザを対象に API 調査/設計する (来週)
以後実装。

必要があればユーザ単位で削除のオンオフが出来ても良いのかもだがひとまずシステム単位で進める (そうしないと動画が残ってるのを減らしたいという大学側の希望が叶わない)

Zoom インポート後の動画削除について，システム単位であれば，オンだけでなく，オフも今回できるであっていますか？

Zoom インポート後の動画削除について，システム単位であれば，オンだけでなく，オフも今回できるであっていますか？

環境変数 ZOOM_IMPORT_AUTODELETE が定義されていれば自動削除するという仕様にしてます。自動削除したくなければ、ZOOM_IMPORT_AUTODELETE を定義せずに運用すれば良いです。

実装作業は以下のissueで

487
488
489
490
インポート後のブック作成は #470

@hATrayflood projects https://github.com/orgs/npocccties/projects/1 に各 issue のカードを (取り組み状況に応じた列に) 配置してくださいませ

実装段階に入っており詳細調整は各 issue の方で進められているのでこちらはクローズしても良いのでは？ (設計変更とか最終的な設計のドキュメント化とかの議論があるならそれはそれで別 issue で良さそうに思う)

npocccties / chibichilo

zoomから動画をインポートする機能の設計調査 #460

~Master account APIs について~

jwt認証

バッチ処理の流れ

バッチの自動実行について

uiの変更

環境変数の追加

db定義の変更

参考資料

処理の流れ

確認事項

実装検討

470 に分離しました

処理の流れ

確認事項

実装検討

487

488

489

490