【Teams】Microsoft Graph APIでチーム一覧を取得するPowerShellスクリプト

Microsoft Teamsのチーム一覧を効率的に取得したい場面があります。しかし、Teamsの管理画面だけでは、すべてのチームを一覧表示・エクスポートする機能が限られています。特に、多数のチームが存在する場合、手作業での確認は困難です。そこで、本記事ではPowerShellとMicrosoft Graph APIを活用して、Teamsのチーム一覧をプログラムで取得する方法を解説します。これにより、組織内のチーム構成を把握し、管理業務を効率化できます。

この記事を読めば、Microsoft Graph APIの基本的な使い方と、PowerShellスクリプトでTeamsのチーム一覧を取得する具体的な手順が理解できます。組織全体のTeams利用状況の把握や、特定の条件に合致するチームの抽出などが可能になります。

Microsoft Graph APIとPowerShellによるチーム一覧取得の仕組み

Microsoft Graph APIは、Microsoft 365の様々なサービスを統一されたRESTful APIで提供するサービスです。TeamsもGraph APIを通じてアクセス可能で、ユーザー情報、チャネル情報、チーム情報などを取得・操作できます。今回の目的であるチーム一覧の取得には、Graph APIの「/groups」エンドポイントを利用します。ただし、TeamsのチームはAzure Active Directory(Azure AD)のグループオブジェクトとして管理されているため、グループ情報を取得することでTeamsのチーム一覧を取得することになります。このAPI呼び出しをPowerShellスクリプトから行うことで、自動化されたチーム情報の収集が可能になります。

PowerShellは、Windows環境でシステム管理タスクを自動化するための強力なコマンドラインシェルおよびスクリプト言語です。Microsoft Graph APIと連携させることで、複雑なAPI操作を比較的容易に実行できます。スクリプト内でAPIリクエストを送信し、返却されたJSON形式のデータを解析して、必要な情報を抽出・整形します。これにより、手作業では時間のかかる大量のチーム情報の確認や管理が効率化されます。

Graph APIを利用するには、まずAzure ADにアプリケーションを登録し、APIへのアクセス許可を与える必要があります。これにより、スクリプトが実行される際に、適切な権限でAPIに接続できるようになります。認証には、クライアントシークレットや証明書を利用する方法がありますが、スクリプトでの利用ではクライアントシークレットが一般的です。この認証プロセスを正しく設定することが、API連携の第一歩となります。

Microsoft Graph APIに接続するための前提条件と準備

PowerShellスクリプトでMicrosoft Graph APIを利用するには、いくつかの前提条件と準備が必要です。まず、Azure ADテナントが必要です。次に、APIにアクセスするためのアプリケーション登録と、必要な権限の付与を行います。さらに、PowerShellからGraph APIを呼び出すためのモジュールをインストールし、認証情報を設定します。これらの準備が完了することで、スクリプトの実行が可能になります。

Azure ADテナントとアプリケーション登録

Microsoft Graph APIを利用するには、Azure ADテナントが必要です。組織のMicrosoft 365環境に紐づくAzure ADテナントがこれに該当します。次に、このテナント内にアプリケーションを登録します。Azureポータルから「Azure Active Directory」>「アプリの登録」>「新しい登録」を選択し、アプリケーション名などを設定します。この登録プロセスで、アプリケーション(クライアント)IDが発行されます。

アプリケーション登録後、APIへのアクセス権限を設定します。今回はTeamsのチーム一覧を取得するため、「Group.Read.All」または「Group.ReadWrite.All」などの委任されたアクセス許可またはアプリケーションのアクセス許可を「グループ」に付与します。スクリプト実行時にユーザーのサインインを必要としない「アプリケーションのアクセス許可」を選択するのが一般的です。権限を付与したら、必ず「管理者の同意を付与」をクリックしてください。

さらに、API認証のためにクライアントシークレットを作成します。アプリケーション登録画面の「証明書とシークレット」から「新しいクライアントシークレット」を作成し、生成されたシークレットの値を安全な場所にコピーしておきます。このシークレット値は、API認証のパスワードとして使用されます。この値は一度しか表示されないため、必ずすぐにコピーして保存してください。

PowerShellモジュールのインストールと認証情報の設定

PowerShellからMicrosoft Graph APIを簡単に利用するために、「Microsoft.Graph」モジュールをインストールします。管理者権限でPowerShellを開き、以下のコマンドを実行します。

1. Microsoft.Graphモジュールのインストール
   Install-Module Microsoft.Graph -Scope CurrentUser

モジュールのインストールが完了したら、Graph APIへの接続を行います。ここでは、アプリケーションID、テナントID、クライアントシークレットを使用した接続方法を説明します。これらの情報は、Azure ADでアプリケーション登録した際に取得したものです。

1. Graph APIへの接続
   Connect-Graph -TenantId “<テナントID>” -ClientId “<アプリケーションID>” -ClientSecret “<クライアントシークレット>“

上記のコマンドを実行する際は、`<テナントID>`、`<アプリケーションID>`、`<クライアントシークレット>`をそれぞれ実際の値に置き換えてください。これにより、PowerShellセッションがMicrosoft Graph APIに認証された状態で接続されます。

Teamsチーム一覧を取得するPowerShellスクリプト

前提条件と準備が整ったら、いよいよTeamsのチーム一覧を取得するPowerShellスクリプトを作成・実行します。このスクリプトは、Microsoft Graph APIの「/groups」エンドポイントに対してクエリを実行し、Teamsチームに該当するグループ情報を取得します。取得した情報の中から、チーム名やIDなどの必要な項目を抽出して表示します。

基本スクリプト: チーム一覧の取得と表示

以下のスクリプトは、Azure ADに登録されたグループの中から、Teamsチームとして有効化されているグループ(resourceProvisioningOptionsに”Team”が含まれるもの)を抽出し、その一覧を表示します。必要に応じて、取得するプロパティを追加・変更できます。

1. Graph APIへの接続
   Connect-Graph -TenantId “<テナントID>” -ClientId “<アプリケーションID>” -ClientSecret “<クライアントシークレット>“
2. チーム一覧の取得
   $teams = Get-MgGroup -Filter “resourceProvisioningOptions/Any(x:x eq ‘Team’)” -All -Property “id,displayName,description”
3. 取得したチーム一覧の表示
   foreach ($team in $teams) { Write-Host “ID: $($team.id), DisplayName: $($team.displayName), Description: $($team.description)” }
4. Graph APIからの切断
   Disconnect-Graph

このスクリプトを実行する前に、`<テナントID>`、`<アプリケーションID>`、`<クライアントシークレット>`を実際の値に置き換えてください。`-Filter`パラメータで`resourceProvisioningOptions`に`Team`が含まれるグループのみをフィルタリングしています。`-All`パラメータは、取得できるグループ数に制限がある場合に、すべての結果を取得するために使用されます。`-Property`パラメータで、取得したいプロパティを指定しています。

取得したチーム一覧をCSVファイルに出力する

取得したチーム一覧を後で分析したり、共有したりするために、CSVファイルとしてエクスポートすると便利です。以下のスクリプトは、前述のスクリプトにCSVエクスポート機能を追加したものです。

1. Graph APIへの接続
   Connect-Graph -TenantId “<テナントID>” -ClientId “<アプリケーションID>” -ClientSecret “<クライアントシークレット>“
2. チーム一覧の取得
   $teams = Get-MgGroup -Filter “resourceProvisioningOptions/Any(x:x eq ‘Team’)” -All -Property “id,displayName,description,mailNickname”
3. 取得したチーム情報をオブジェクトに変換
   $teamObjects = foreach ($team in $teams) { [PSCustomObject]@{ ID = $team.id; DisplayName = $team.displayName; Description = $team.description; MailNickname = $team.mailNickname } }
4. CSVファイルとしてエクスポート
   $teamObjects | Export-Csv -Path “C:\Temp\TeamsList.csv” -NoTypeInformation
5. Graph APIからの切断
   Disconnect-Graph

このスクリプトでは、取得したチーム情報を`[PSCustomObject]`を使用してオブジェクトに変換しています。これにより、`Export-Csv`コマンドレットで扱いやすくなります。`-Path`パラメータで出力先のCSVファイルのパスを指定しています。必要に応じて、取得するプロパティや出力ファイル名を変更してください。

特定の条件でチームを絞り込む高度なクエリ

Microsoft Graph APIでは、ODataクエリ構文を使用して、より詳細な条件でグループをフィルタリングできます。例えば、特定の表示名を持つチームのみを取得したり、説明文に特定のキーワードが含まれるチームを検索したりすることが可能です。以下は、表示名に「プロジェクト」という単語を含むチームを検索する例です。

1. Graph APIへの接続
   Connect-Graph -TenantId “<テナントID>” -ClientId “<アプリケーションID>” -ClientSecret “<クライアントシークレット>“
2. 表示名に「プロジェクト」を含むチームの取得
   $teams = Get-MgGroup -Filter “resourceProvisioningOptions/Any(x:x eq ‘Team’) and startsWith(displayName, ‘プロジェクト’)” -All -Property “id,displayName”
3. 取得したチーム一覧の表示
   foreach ($team in $teams) { Write-Host “ID: $($team.id), DisplayName: $($team.displayName)” }
4. Graph APIからの切断
   Disconnect-Graph

`-Filter`パラメータの条件を組み合わせることで、より複雑な絞り込みが可能です。例えば、`and endsWith(displayName, ‘部’)`で末尾が「部」で終わるチームを検索したり、`and contains(description, ‘非公開’)`で説明に「非公開」を含むチームを検索したりできます。Graph APIのフィルタリング機能は非常に強力なので、必要に応じてMicrosoft Graph APIのドキュメントを参照して、利用できる演算子やプロパティを確認してください。

新しいTeams(v2)と従来Teamsでの違い

Microsoft Graph APIを利用してTeamsのチーム一覧を取得する操作において、新しいTeams(v2)と従来Teamsの間で直接的な大きな違いはありません。これは、Teamsのチーム情報が基盤となるAzure ADのグループオブジェクトとして管理されており、Graph APIはこれらのグループオブジェクトにアクセスするためです。そのため、本記事で紹介したPowerShellスクリプトは、新しいTeams環境でもそのまま利用可能です。

新しいTeams(v2)は、主にユーザーインターフェースやパフォーマンスの改善、一部機能の統合に焦点が当てられています。バックエンドのデータ構造やAPIの提供方法に根本的な変更がない限り、既存のGraph APIエンドポイントで取得できる情報や、その取得方法は変わりません。したがって、チームの作成、削除、メンバー管理、チャネル情報の取得など、他のTeams関連操作においても、Graph APIを利用する限りは大きな影響はないと考えられます。

ただし、将来的にMicrosoft Graph APIの進化やTeamsの機能拡張に伴い、新しいチーム固有のプロパティが追加されたり、既存のAPIの動作が変更されたりする可能性はゼロではありません。そのため、最新の機能を利用したい場合や、予期せぬ動作が発生した場合は、Microsoft Graph APIの公式ドキュメントで最新情報を確認することが重要です。

Mac版・モバイル版・Web版での違い

本記事で紹介したPowerShellスクリプトは、主にWindows環境を想定しています。PowerShell自体はmacOSやLinuxでも実行可能ですが、Microsoft Graph APIへの接続やモジュールのインストール方法に違いが生じます。macOSやLinuxでPowerShell Core (pwsh) を使用する場合、`Install-Module`コマンドは同様に機能しますが、環境によっては追加の設定が必要になることがあります。

モバイル版TeamsやWeb版Teamsでは、直接PowerShellスクリプトを実行することはできません。これらのプラットフォームは、ユーザーインターフェースを通じてTeamsの機能を利用するためのものであり、サーバーサイドのスクリプト実行環境を提供していません。もし、モバイルデバイスやWebブラウザからTeamsのチーム一覧を取得したい場合は、Microsoft Graph ExplorerのようなWebベースのAPIテストツールを利用するか、別途サーバーサイドでスクリプトを実行し、その結果をWebアプリケーションなどで表示するなどの方法が考えられます。

管理者権限について: PowerShellスクリプトを実行する際に、`Install-Module`コマンドでモジュールをインストールする場合や、Azure ADテナントへの変更を伴う操作(アプリケーション登録など)を行う場合は、管理者権限が必要です。ただし、`Connect-Graph`コマンドレットでAPIに接続し、既存のグループ情報を参照するだけであれば、通常は管理者権限は必須ではありません。ただし、組織のポリシーによっては、APIアクセスに制限が設けられている場合もあります。

よくある質問とトラブルシューティング

Microsoft Graph APIを利用してTeamsのチーム一覧を取得する際に、予期せぬ問題が発生することがあります。ここでは、よくある質問とそれに対するトラブルシューティング方法を解説します。

「アクセスが拒否されました」というエラーが表示される

このエラーは、主にAPIへのアクセス権限が不足している場合に発生します。以下の点を確認してください。

1. アプリケーションのアクセス許可の確認: Azure ADで登録したアプリケーションに、「Group.Read.All」などの必要なアクセス許可が付与されているか確認してください。
2. 管理者の同意の確認: 付与したアクセス許可に対して、管理者の同意が完了しているか確認してください。同意がまだの場合は、「管理者の同意を付与」ボタンをクリックしてください。
3. クライアントシークレットの有効期限: クライアントシークレットには有効期限があります。期限が切れている場合は、新しいシークレットを生成し、スクリプトを更新してください。

取得できるチームが少ない、または期待したチームが表示されない

これは、フィルタリング条件が正しくないか、あるいは取得対象のグループがTeamsチームとして正しく認識されていない可能性があります。以下の点を確認してください。

1. フィルタリング条件の見直し: `-Filter`パラメータで指定している条件が、意図したチームを正しく抽出できているか確認してください。特に、`resourceProvisioningOptions/Any(x:x eq ‘Team’)`の部分が重要です。
2. グループのタイプ確認: 取得したいチームが、Azure AD上で「Teams」としてプロビジョニングされているか確認してください。一部のグループ(Microsoft 365グループでTeamsが有効化されていないものなど)は、このフィルタリングでは除外されます。
3. `-All`パラメータの利用: 取得できるグループ数に制限がある場合、`-All`パラメータを付けていないと、一部のグループしか取得できないことがあります。

`Connect-Graph`コマンドレットが見つからない

これは、`Microsoft.Graph`モジュールが正しくインストールされていないか、PowerShellセッションに読み込まれていない場合に発生します。

1. モジュールの再インストール: `Install-Module Microsoft.Graph -Scope CurrentUser`コマンドを再度実行し、モジュールをインストールしてください。
2. PowerShellの再起動: PowerShellを一度終了し、再度起動してからコマンドレットを実行してください。
3. モジュールのインポート確認: `Get-Module Microsoft.Graph`コマンドでモジュールが読み込まれているか確認できます。必要であれば`Import-Module Microsoft.Graph`を実行してください。

まとめ

本記事では、PowerShellとMicrosoft Graph APIを利用して、Microsoft Teamsのチーム一覧を取得する方法を解説しました。Azure ADでのアプリケーション登録、必要な権限の付与、PowerShellモジュールのインストールと接続設定を経て、チーム情報をプログラムで取得・CSVファイルに出力するスクリプトを作成しました。これにより、組織内のTeams利用状況の把握や管理業務の効率化が期待できます。

次に取り組むべきステップとしては、取得したチーム一覧を基に、特定の条件(例: 所有者がいないチーム、最終アクティビティが古いチームなど)でさらに詳細な分析を行うスクリプトを作成することが挙げられます。Microsoft Graph APIは多機能なため、チーム情報だけでなく、チャネル情報やメンバー情報なども取得し、より包括的なTeams管理を実現することも可能です。

このスクリプトをベースに、組織のニーズに合わせてカスタマイズし、Teams管理の自動化を進めてみてください。

👥

Teams/Outlookトラブル完全解決データベース サインイン、接続エラー、メール送受信の不具合など、特有のトラブル解決策を網羅。困った時の逆引きに活用してください。