組織内の全ルーム一覧・各ルームの参加メンバー一覧を取得する方法について

Yuka1 · ‎2019-01-16

いつもお世話になっております。

現在、組織(Control Hub)内のWebex Teamsユーザーが参加している全ルームの一覧および各ルームの参加メンバーを取得する方法を探しています。

検証した結果、WebexTeamsAPIを使用して、自分の参加するルームの一覧を取得し、ルームIDからそのルームの参加メンバー一覧を取得する方法までは判明しています。

ですが、自分の参加するルームだけでなく、他のユーザー(並びに組織内の全ユーザー)が参加するルームの一覧を取得する方法が分かりません。

APIで実現可能であればその方法を教えていただけないでしょうか。何卒よろしくお願いいたします。

Tohru Ohzono · ‎2019-01-17

該当の機能を実現するには、コンプライアンスオフィサーの権限が必要となります。
Webex TeamsのREST APIは、通常は、APIリクエスト時に認可されるユーザのアクセス範囲内のみのリソースへの処理が可能です。
コンプライアンスオフィサーの権限を利用することで、該当のコンプライアンスオフィサーユーザが所属しない、
スペースやメッセージの処理が可能になります。

おおまかな手順は以下のようになります。
1. Integrationを使って、APIアクセス用のトークンを取得する。
この際にOAuth2の認可手順でログインするユーザには、コンプライアンスオフィサーのアカウントを利用。
2. 取得したトークンを使って、List Eventsで、membershipsのイベント一覧を取得する。
この一覧内に、スペースへの参加情報やユーザID, スペースIDなどが含まれます。

コンプライアンスオフィサーを利用するには、通常、Webexの有償契約が必要ですが、
Control Hubをお使いのようなので、既に利用可能だと思います。

Control Hubのユーザ設定で、[ロールとセキュリティ]で、
[コンプライアンスオフィサー]のチェックが付いたユーザを作成します。
※ セキュリティなどの観点から、コンプライアンスオフィサーとしての
専用アカウントとした方がよいと思います。

--- 以上で、コンプライアンスオフィサーの準備は完了です。 ---

アプリケーション側でも各種考慮が必要となります。
上記のコンプライアンスオフィサーとは"別のWebexアカウント"を使って、
Integrationアプリを作成、管理します。
※ セキュリティなどの観点から、アプリケーションの作成は、
コンプライアンスオフィサーのアカウントとは別アカウントを利用した方がよいです。

https://developer.webex.com/
にアプリを作成、管理するアカウントでログインします。
[ユーザアイコン] -> [My Webex Teams Apps] -> [Create a New App]の順に選んで、
[Create an Integration]の順に選びます。

以下も参考に、OAuth2を使ったIntegrationに必要な情報を埋めていきます。
https://developer.webex.com/docs/integrations

[Scopes]の設定で、必要最低限度のアクセスレベルを選択していきます。
※ セキュリティなどの観点から、必要ないものは選ばないようにします。

スペース名と所属するユーザのIDなどが取得できれば良いのであれば、
以下の権限のみで実現可能だと思います。
spark-compliance:events_read
spark-compliance:memberships_read
spark-compliance:rooms_read

チーム情報も必要なのであれば、以下も必要になります。
spark-compliance:team_memberships_read
spark-compliance:teams_read

※ お問い合わせ内容の機能であれば、上記以外は必要ないはずですので、
不必要な権限はチェックしないようにします。

設定が終わったら、[Add Integration]ボタンを押して、Integrationを作成完了します。

--- 以上で、Integrationの作成は完了です。 ---

作成したIntegrationを利用したアプリを実装する必要があります。

APIにアクセスするためのトークンは、OAuth2の手順で取得するように実装します。
https://developer.webex.com/docs/integrations

トークン取得までの過程で、認可のためにログイン画面が表示されますが、
ここで、コンプライアンスオフィサーのアカウントを利用して、
認証、認可を受ける必要があります。

トークンが取得できれば、通常のWebex REST APIと同様に必要なAPIを呼び出していきます。

ご質問の目的であれば、List Eventsが利用できるはずです。
https://developer.webex.com/docs/api/v1/events/list-events

"resource"を"memberships"、"type"を"all"などに設定すると良いと思います。
これで、スペースへメンバーが追加、削除、更新されたイベントが一覧で取得できます。

取得したイベントにmembershipIdやroomIdなどが含まれます。
Get Spaceや、Get MembershipなどのAPIにこれらを渡すことでスペース名などの取得も可能です。

なお、List Spacesは、認証したユーザが参加するスペースの一覧なので、目的の機能には利用できないと思います。

Event APIで現在利用できる"resource"は、"messages"または"memberships"になります。

詳細は、こちらも参照ください。
https://developer.webex.com/docs/api/guides/compliance

※ 以下、特別考慮すべき点となります。

コンプライアンス機能はアクセス可能な範囲が広くなるので、ご利用や実装時に純分ご注意ください。
1. IntegrationのScopeに不必要なアクセスレベルは設定しないようにします。
2. コンプライアンスオフィサーのID、パスワードを流出しないような管理が必要です。
3. Integrationの[Client Secret]を保護する必要があります(流出させない、暗号化して保存など)。
4. OAuth2で取得した"access_token"と"refresh_token"は共に保護する必要があります(流出させない、暗号化して保存など)。

Yuka1 · ‎2019-01-17

いつもお世話になっております。

丁寧なご回答をありがとうございます。大変参考になります。

コンプライアンスオフィサーの権限を使用したIntegrationを作成し、アプリ側でLists EventのAPIを呼び出せば
スペースへメンバーが追加、削除、更新されたイベントが一覧で取得できるとのことですが、
組織内にインポートしたフリーユーザーに関する、インポートする以前のイベントについても取得することは可能でしょうか。

例えば、フリーユーザーAがスペース1に参加したと仮定します。その後、フリーユーザーAを自組織内にインポートしました。
次に、Lists EventのAPIを呼び出した場合、フリーユーザーAがスペース1に参加したというイベントは取得可能でしょうか。
おそらく、組織へインポートする以前の情報なので取得できないのではないかと思います。

(組織へのインポート後は、スペース1のメンバーの変更は無いものとします)

この質問には、フリーユーザーをインポートする際、そのフリーユーザーが参加しているスペースの中に、自組織以外のユーザーがいるかどうかを検知したいという背景がございまして、検知するためには組織内の全ユーザーの参加するスペース一覧および参加メンバー一覧が必要なのではと考え、先日の質問に至りました。

ご提示いただいた方法で、フリーユーザーに関するインポートする以前のイベントも取得可能でしたら早速検証させていただきますので、お手数ですが可否についてご回答いただけますでしょうか。
よろしくお願い申し上げます。

Tohru Ohzono · ‎2019-01-18

組織に紐づいていないユーザから、組織内のユーザに変換した場合ですが、
組織に紐づける前のイベントは記録されないので、
組織に紐づく前の活動も含めた目的の情報をEventだけから取得することはできません。

スペース内で組織に紐づけたユーザがメッセージの投稿、削除を１度でも行えば、
"message resource"はイベントとして記録されます。

※ あるスペースには所有権の概念があるので、スペースが作成された時点で、
スペース作成者の組織に所属するスペースになります。
イベントは自分の組織に関するものだけ記録されるので、
他組織作成のスペース内で、他組織のユーザの投稿に関してはイベントとして取得できません。
自分の組織作成のスペース内のメッセージ、または、他組織の作成のスペース内で、
自分の組織のユーザが投稿、削除したメッセージはイベントとして記録されます。
よって、紐づけ前に参加していた他組織所有スペースの情報をイベントから取得するには、
そのスペース内で、紐づけしたユーザがメッセージを投稿、削除した場合になります。

なお、スペースの参加者(memberships)の変更に関しても、メッセージの場合と同様に、
現時点では、スペースの所有権の概念があり、自分の組織所有のスペースのみイベントに記録されます。
参加者(memberships)のイベント記録には改善の予定があり、
まもなく、所有権のないスペースへの参加者変更に関しては、
組織内のユーザが参加しているスペースであれば、イベントが記録されるようになる予定です。

以上、踏まえると、目的の情報をあらゆる状況を考慮して、
完ぺきな形で取得することはできませんが、
あえてやるなら以下のような方法が考えられるかもしれません。

Integrationは２種類作成して、１つは前回回答分のコンプライアンスオフィサー用のもの、
もう１つは、エンドユーザ用のIntegrationを作成します。
また、通知用のBotを１つ作成します。

エンドユーザ用のIntegrationの[Scopes]は、
"spark:people_read", "spark:rooms_read"のみ入れておきます。

ユーザの紐づけを行った後は、Botを使って、ユーザに通知を行い、
エンドユーザ用のIntegrationにアクセスしてもらって、
"/v1/people/me"でアクセスしたユーザの特定、
"/v1/rooms"で該当ユーザがその時点で所属するスペース一覧の取得を行います。

エンドユーザのIntegrationで、membershipsまで一覧取得してもよいですが、
roomIdだけ取っておけば、コンプライアンスオフィサーの権限でも、
membershipsの一覧は取得できます。

エンドユーザがIntegration利用するまでは、定期的にBotで通知するなどしたうえで、
組織紐づけ後のスペース参加状況に関しては、Eventから判断するようにします。

エンドユーザ側に１度のみ、
Integrationにアクセスしてもらう必要があるのと、
Integration使ったあとでしか情報取得できないので、現実的な方法ではないかもしれませんが、
今のところ、私の方で考えられるのは上記のような方法となります。

なお、この方法の場合は、
組織に紐づける前に参加していて、紐づけ前に退出したスペースの情報に関しては、
一切分かりません。
紐づけ後に退出したスペースであれば、ユーザ用のIntegration利用前でも、Eventに記録されているはずです。
また、退出後にスペースの参加者に自分の組織の人が１人も存在しない状態になっている場合は、
コンプライアンスオフィサーでも、該当スペースのmembershipsの一覧を新規に取得することはできなくなります。
(membershipsがイベントに記録される状況である場合は、イベントからある程度判断はできます。)

Yuka1 · ‎2019-01-22

いつもお世話になっております。迅速なご回答ありがとうございました。

前回回答いただいた案に加え、エンドユーザー用のIntegrationと通知用botを併用することで実現できるのではとのこと、承知いたしました。実現方法案として参考にさせていただきます。

ここからは要望になりますが、Pro Pack Cisco Webex Control Hubの「外部コミュニケーションを制限する」機能が、

組織にフリーユーザーを紐づける際にも適用されると大変嬉しいです。

現状、フリーユーザーが組織へ紐づけられる前に参加しているスペースについては、上記の機能の適用範囲外となり

組織へ紐づけ後もそのスペース内に限っては外部ユーザーとのコミュニケーションが可能であると認識しています。

(そのスペースへ新たなユーザーを参加させることはできないが、既存ユーザー同士の投稿は引き続き可能)

組織に属するユーザーを全てControl Hub側で作成してしまえば良いというのは理解しておりますが、
大規模組織の場合、管理者側の負担削減の観点からエンドユーザー自身にアカウントを作成してもらい、

その後組織へ紐づけるという方法を選択せざるを得ません。

ですので、組織へ紐づける際に、フリーユーザーの参加しているスペースの中に自組織以外のユーザーが参加しているスペースがあれば、強制退出させるもしくはそのスペースをリストアップし以後監視するといったことが簡単にできると、セキュリティ・運用の両面で非常に有効だと思います。

質問対し丁寧にご回答いただきありがとうございました。以上でクローズいただいて結構です。

よろしくお願い申し上げます。

Tohru Ohzono · ‎2019-01-22

ご連絡ありがとうございます。

ご要望の件は、社内でも検討いたします。