【Teams】Add-TeamUser と Remove-TeamUser でのユーザーの追加や削除が Teams に反映されない場合の注意点
Teams PowerShell を使用してチームのメンバーシップを変更した際、コマンドが正常終了してから、実際に Teams に反映されるまでに時間を要す場合があります。そして、変更を反映をトリガーさせるには、Teams アプリを開いておく必要があるようです。コマンドのリファレンスにも注意事項としてされていますが、かなり気づきにくいので関連する記事や動作についてまとめておきます。
公開情報
公式のリファレンスは以下になります。(英語の記事のみ)
※ 2020 年 12 月時点の記事の内容を抜粋しており、今後サービス側で変更される可能性もあるため公開情報を適宜参考にしてください。
Add-TeamUser コマンドの記事では、コマンドの実行後すぐには反映されず、反映までに 24 -48 時間要する可能性があることが記載されています。
Add-TeamUser (MicrosoftTeamsPowerShell) | Microsoft Docs
The command will return immediately, but the Teams application will not reflect the update immediately. The change can take between 24 and 48 hours to appear within the Teams client.
一方、Remove-TeamUser の記事では、反映までに 24 - 48 時間要する可能性があることに加え、変更を反映させるために Teams アプリを最大 1 時間開いておく必要があると記載されています。
Remove-TeamUser (MicrosoftTeamsPowerShell) | Microsoft Docs
Note: the command will return immediately, but the Teams application will not reflect the update immediately. The Teams application may need to be open for up to an hour before changes are reflected.
つまり、単にコマンドを実行するだけでは、チームのメンバーシップを変更したことが Teams に変更されない可能性があるということです。
コマンドの中身は Graph API
Teams PowerShell のコマンドを実行すると、内部的には処理に対応するエンドポイントの Graph API がコールされます。これは、Web 系の開発でよく使われる Fiddler などの通信をキャプチャするツールを使用すると確認できます。
例えば、Add-TeamUser の場合は、Graph API の /groups/ エンドポイントが呼ばれて処理されていることがわかります。
Teams のチームは Azure AD の Microsoft 365 グループで管理されているので、Graph API の /groups/ エンドポイントの API を使用してグループにユーザーを追加しているようですね。
完全に蛇足ですが、通信をキャプチャした結果から、Add-TeamUser は以下の流れで処理をしていることがわかります。
- /users/ エンドポイントに GET 要求し、コマンド実行時に指定したユーザーの情報を取得
- /groups/ エンドポイントに GET 要求で、該当のユーザーが M365 グループに存在しているかをチェック ※上記画像ではユーザー (リソース) が存在しなかったので 404 のステータスで応答)
- /groups/ エンドポイントに POST 要求で、該当のユーザーを追加
Remove-TeamUser の場合も、同様の流れで Graph API の /groups/ エンドポイントを使用して、M365 グループからユーザーを削除しています。
ここから Teams PowerShell を使用したグループのメンバーシップ変更が Teams に即時反映されない動作は、Graph API の動作に起因していることがわかります。
変更が同期される条件
Add-TeamUser / Remove-TeamUser コマンドの中身は Graph API であることがわかりました。そこで Graph API 側のリファレンスを確認すると、メンバーシップの変更が同期される仕組みについて記載があります。
チームが作成された後にメンバーを追加するには、［メンバーの追加］操作をします。 追加操作の間に 1 秒の遅延を追加することをお勧めします。
メンバーシップの変更に関しては、次の点にご注意ください。Microsoft 365 グループに対して行われたメンバーシップの変更は、通常 24 時間 (場合によってはそれ以上) を必要とするバックグラウンド同期メカニズムによって、Teams と同期します。
このバックグラウンドプロセスは、チーム内の1人以上のユーザー（所有者もしくはメンバー）が Teams デスクトップクライアントでアクティブになっている場合にのみ実行されます。チームアプリケーションを起動したり実行することはアクティビティになります。ユーザーは、特に変更されているチームにアクセスをする必要はありません。
注: Teams のモバイルクライアントは、メンバーシップの同期を実行しません。このバックグラウンドプロセスが円滑に動作するように、少なくとも1人のユーザーがデスクトップクライアントにログオンしている必要があります。
自分の解釈では以下ようになります。
- Microsoft 365 グループに対して実行したメンバーシップの変更 (ユーザーの追加や削除) は、Azure AD から Teams へのバックグラウンドでの同期処理により反映される
- バックグラウンド処理がトリガーされるためには条件がある
- メンバーシップを変更した M365 グループ (チーム) に所属する任意のユーザーが、Teams デスクトップアプリを開く (ログイン) することで M365 グループから Teams への同期がトリガーされる
また、同期がトリガーされ、M365 グループから Teams アプリへの同期処理が完了するまでに 24 時間程度要することが想定されるため、結果的に、Teams の PowerShell コマンドはエラー無く終了したにも関わらず、Teams 上ではその変更が反映されていないように見えてしまう状況が発生しうることになるようです。公開情報によるとモバイル版の Teams では同期処理をトリガーしないとありますが、Web 版の Teams アプリについては言及がありません。Teams デスクトップと明記していることから、Teams デスクトップアプリを使用することが無難かと思います。
おわりに
テナントによっては、特に新しいチームを作成するような状況では、ユーザー側に直接チームの管理を任せておらず、管理者が PowerShell などで事前にユーザーを追加するような運用もあるかと思います。Add-TeamUser / Remove-TeamUser コマンドでユーザーの追加/削除をしたのに、Teams アプリ上でみるとチームのメンバーが変化していないなどの状況が起きたら、チームに所属するユーザーが Teams のデスクトップアプリを起動して、時間経過により反映されるようになるかを確認する必要がありそうです。
なお、チームの作成からメンバーの追加をまとめて Teams PowerShell で行っている場合、チームの作成者がチームの所有者 (Owner) になっていると思います。この場合は、コマンドを実行するユーザーが Teams デスクトップアプリを起動しておけば、チームの任意のユーザーが Teams デスクトップアプリにサインインするという上限を満たせると思います。手元の環境で検証する限り、デスクトップアプリを起動していなくても反映されることがあったので、必須ではないのかもしれませんが、もし Teams にメンバーシップの変更が反映されない状況になったら、注意してみてください。
チーム作成やメンバーの変更に関するチェック項目も記載があるので、Teams に変更が同期されていないなと思ったら、下記チェック項目も確認してみることをお勧めします。
https://docs.microsoft.com/ja-jp/graph/teams-create-group-and-team?source=docs#checklist-for-validationMicrosoft Graph を使用してチームの作成と、メンバーを管理する - Microsoft Graph | Microsoft Docs
今回の投稿は以上です。
