M365Con 2027 – 無料オンラインカンファレンス · 11–22 Jan 2027 · 120 sessions→ m365con.net

ブログ · Mirko Peters

SharePoint管理者のための Microsoft Graph PowerShell: 最初のコマンド

By · · Updated

SharePoint向けの Microsoft Graph PowerShell: SDKのインストール、適切なスコープでのサインイン、Get-MgSite によるサイトの一覧表示、管理者が最初に遭遇する403エラーの解決方法を解説します。

Automatically translated with AI from the original post. Read the English original

SharePoint向けの Microsoft Graph PowerShell とは、Graph SDK を使って、コマンドラインからサイトを読み取り、管理することを指します。モジュールを1つインストールし、Connect-MgGraph とアクセス許可のスコープを指定してサインインし、Get-MgSite などのコマンドレットを実行します。このガイドは、SharePoint 管理センターをすでに使いこなしていて、安全にスクリプト化を始めたい SharePoint 管理者を対象としています。SDK のインストール、動作する最小のスコープでのサインイン、サイトの一覧表示、最初に表示されるエラーの読み方を順に説明します。

重要なポイント

  • Microsoft Graph PowerShell は Graph API をラップする SDK です。そのため、どのコマンドを実行する前にも、適切なアクセス許可スコープを指定して Connect-MgGraph でサインインする必要があります。
  • Get-MgSite は SharePoint サイトを一覧表示するコマンドで、最低限 Sites.Read.All のアクセス許可が必要です。これは Microsoft が文書化している、このコマンドに対する最小権限の選択肢です。
  • Get-MgContext は、現在のセッションがどのスコープを保持しているかを表示します。403 Forbidden エラーの原因を最も手早く確認できる方法です。
  • Find-MgGraphCommand と Find-MgGraphPermission を使うと、コマンドに必要なアクセス許可がわかるため、スコープ名を推測する必要がありません。
  • 委任によるサインインは、キーボードの前にいる個人が操作する場合に適しています。一方、証明書またはマネージド ID を使うアプリ専用のサインインは、無人で実行されるジョブに適しています。

Microsoft Graph PowerShell とは何か、管理者がなぜ使うのか

Microsoft Graph は、ユーザー、グループ、ファイル、メール、Teams、SharePoint サイトなど、Microsoft 365 データを扱うための単一の API です。Microsoft Graph PowerShell SDK は Graph API をコマンドレットとして包んでいます。各エンドポイントに対して Web 要求を書く必要はありません。Get-MgSite を実行すると、サイトのオブジェクトが返されます。

SharePoint 管理者にとって、これには実用的なメリットが3つあります。

  • サービスをまたいで使える1つのツール。 同じサインインで、サイト、ユーザー、グループを扱えます。スクリプトでサイトを一覧表示し、そのサイトの所有者を調べるといったことも可能です。
  • 読みやすいアクセス許可モデル。 すべての呼び出しには、スコープと呼ばれる名前付きのアクセス許可が必要です。セッションがどのスコープを保持しているか、また呼び出しがなぜ拒否されたかを確認できます。
  • 古いモジュールからの移行先。 Microsoft Graph PowerShell の解説では、廃止された Azure AD PowerShell と MSOnline モジュールの後継として位置付けられています。

コミュニティ製の PnP PowerShell モジュールも、SharePoint スクリプティングで一般的に選ばれるもう1つの選択肢です。そのドキュメントには、一部のコマンドレットが Graph とも通信すると記載されています。Graph PowerShell がすべての SharePoint 管理ツールを置き換えるわけではありません。対象は Graph API が公開している範囲に限られます。テナントの一部の設定は、依然として SharePoint 管理センターや別のモジュールで管理します。Graph は、使うツールの1つとして位置付けてください。唯一のツールとして扱う必要はありません。

手順1: SDK のインストールとサインイン

インストール ガイドでは、すべてのプラットフォームで PowerShell 7 以降の使用が推奨されています。Windows PowerShell の場合は、バージョン 5.1 以降、.NET Framework 4.7.2 以降、および RemoteSigned 以下に制限された実行ポリシーが必要です。

次の手順に従ってください。

  1. 自分のアカウント用にモジュールをインストールします: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force。共有インストールが必要で、管理者権限がある場合のみ -Scope AllUsers を使用してください。
  2. Get-InstalledModule Microsoft.Graph で結果を確認します。
  3. メインモジュールは 47 個以上のサブモジュールをインストールすることに注意してください。ページでは必要なものだけをインストールできると説明されており、Microsoft.Graph.Authentication も同梱されています。
  4. 後で Update-Module Microsoft.Graph で更新します。古いモジュールは、バージョンの競合の原因として挙げられています。

あるバージョンの PowerShell にインストールしても、もう一方のバージョンにはインストールされません。使用するバージョンでコマンドを実行してください。

次にサインインします。認証コマンドのページでは、SDK が 2 種類のアクセス方法をサポートしていると説明されています。委任アクセスはサインインしたユーザーとして動作し、そのアクセス許可はスコープで表されます。アプリ専用アクセスはユーザーなしで動作し、証明書、クライアント シークレット、またはマネージド ID を使用します。

最初のコマンドでは、委任アクセスを使用し、読み取り専用のスコープを 1 つ要求します。

Connect-MgGraph -Scopes "Sites.Read.All"

サインイン用のブラウザー ウィンドウが開きます。取得できた内容を確認するには、Get-MgContext | Select -ExpandProperty Scopes を実行します。Microsoft のドキュメントでは、Get-MgContext は現在のセッションの詳細(クライアント ID、テナント ID、スコープ、認証の種類など)を返すコマンドとして説明されています。作業が終わったら Disconnect-MgGraph を実行してください。ページによると、トークンは既定の CurrentUser スコープにキャッシュされるため、切断するまでサインインした状態が維持されます。サインインを現在のセッションのみに限定したい場合は、Connect-MgGraph に -ContextScope Process を追加してください。

SharePoint サイトに対する最初のコマンド

Get-MgSite のリファレンスには、主なパラメーターが記載されています。-Filter、-Search、-Property(エイリアスは -Select)、-Top、-Sort、-All です。ページ内の例は短いものです。

  • Get-MgSite でサイトを一覧表示します。
  • Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null" は、2 つのプロパティを含むルート サイト コレクションのみを返します。

ここから段階的に応用します。

  1. ページングして一覧表示。 Get-MgSite -All を実行すると、すべてのページの結果を取得できます。-All を付けないと、最初のページしか表示されない場合があります。
  2. 列を選択。 -Property "id,displayName,webUrl" を追加すると、出力が小さく読みやすくなります。
  3. キーワードで検索。 Get-MgSite -Search "finance" を実行します。Graph の検索 API は、複数のサイト プロパティに対して自由テキストで照合します。
  4. 1 つのサイトを取得。 Get-MgSite -SiteId <id> を実行します。ここでの ID は、前の結果にある id の値です。ホスト名、続いてカンマで区切られた 2 つの GUID という形式です。

これらのコマンドレットはいずれも REST 呼び出しに対応しています。Get-MgSite -All は、REST のドキュメントでサイトの一覧表示に使われている https://graph.microsoft.com/v1.0/sites の sites コレクションを読み取ります。-Filter、-Search、-Property は、この URL のクエリ オプションになります。SDK は Microsoft Authentication Library(MSAL)を通じてトークンを取得します。必要な呼び出しに対応するコマンドレットがない場合は、Invoke-MgGraphRequest で URI を直接呼び出せます。トラブルシューティングのページでは、「Bad request」エラーの背後にある URI を確認するためにこのコマンドを使用しています。

注意すべき制限が 2 つあります。1 つ目は、Graph の一覧エンドポイントが返すサイトは、組織の既定の地理的な場所に限られることです。すべての地理的な場所を対象にする場合、Microsoft は getAllSites API を案内しており、これはコマンドレット Get-MgAllSite に対応します。2 つ目は、検索 API が並べ替えできるのは createdDateTime のみであることです。

どのアクセス許可が必要ですか?Microsoft Graph PowerShell と SharePoint のスコープ

新しいユーザーが戸惑いやすいのは、Microsoft Graph のアクセス許可です。サイトの読み取りについて、コマンドレットのページでは、最小特権の選択肢として Sites.Read.All、より高い特権の選択肢として Sites.ReadWrite.All が挙げられています。スクリプトで何かを変更する必要がない限り、前者を選んでください。

スコープ名を覚えておく必要はありません。検索に使える補助コマンドが2つあります。

  • Find-MgGraphCommand は、コマンドレットや API に必要なアクセス許可を表示します。トラブルシューティングのページでは、例として Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions が使われています。
  • Find-MgGraphPermission は、領域や名前からアクセス許可を検索します。例えば Find-MgGraphPermission application のように使います。出力には、種類(委任またはアプリケーション)、管理者による同意が必要かどうか、説明が表示されます。

ドキュメントには、食い違いが一点あります。サイト一覧の取得に関する REST のページでは、その呼び出しにアプリケーションのアクセス許可だけが示され、委任アクセスはサポートされていないと記載されています。一方、Get-MgSite のコマンドレットのページでは両方が挙げられています。実際の呼び出しは非運用環境のテナントで検証し、失敗した場合はエラーメッセージを読んでください。コマンドレットのページがすべての呼び出しに当てはまると決めつけないでください。

無人で実行するジョブには、アプリ専用のアクセスが必要です。つまり、Microsoft Entra でのアプリの登録、アプリケーションのアクセス許可(API のアクセス許可とも呼ばれます)、そして管理者の同意が必要になります。トラブルシューティングのページでは、アプリケーションのアクセス許可には管理者の同意が必要だと説明されています。パスワードを直接入力するのではなく、証明書またはマネージド ID を使用してください。

例:5つのコマンドで古いサイトの一覧を作成する

この例の数値は仮のものです。

管理者が、1年間誰も変更していないサイトの最初の一覧を作りたいとします。

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. この例では、$sites.Count の結果は 480 になります。
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation

ファイルに 60 行あるとします。480 件中 60 件、つまり 12.5 パーセントです。サイト所有者と確認するには、ちょうどよい短い一覧です。管理者は読み取りアクセスのみを使い、何も変更していません。サイトの最終更新日が古いからといって、誰も使っていないとは限りません。そのため、この一覧は削除対象のリストではなく、質問を始めるための出発点として使ってください。

よくある間違い

  • スコープを指定せずにサインインする。 適切なスコープを指定せずにサインインすると、403 エラーが発生します。Get-MgContext を実行して、スコープがコマンドレットに必要なものと一致しているか確認してください。
  • 読み取り作業に書き込み用のスコープを要求する。 レポートの作成には Sites.ReadWrite.All は必要以上です。まずは Sites.Read.All から始めてください。
  • -All を忘れる。 これを指定しないと、最初のページだけなのに、一覧が完全に見えてしまうことがあります。
  • モジュールのバージョンを取り違える。 Microsoft はスクリプトには v1.0 モジュールの使用を推奨しています。beta モジュールはプレビュー段階で、予告なく変更される可能性があります。
  • 更新を省略する。 古い Microsoft.Graph のバージョンは、バージョンの競合の原因として挙げられています。ほかの原因を調べる前に、Update-Module Microsoft.Graph を実行してください。
  • 共有マシンでサインインしたままにする。 トークンはキャッシュされます。作業が終わったら Disconnect-MgGraph を実行してください。

ソフトウェアが役立つ場面

初めての作業の多くは、すでに持っているツールで対応できます。Microsoft Graph PowerShell SDK は、読み取りとエクスポートを担えます。SharePoint 管理センターでは、コードを書かなくてもサイトの一覧や設定を確認できます。Excel や Power BI を使えば、CSV をサイト所有者が読みやすいレポートにできます。定期実行が必要な場合は、Azure Automation でマネージド ID を使ってスクリプトを実行できます。

ギャップを探すのは、1 か月ほど運用してからで十分です。同じ一覧を手作業で作り直しているなら、出力先フォルダーを固定したスクリプトを保存し、毎月のリマインダーを設定するだけで、たいていは足ります。

次のステップ

今日のうちに SDK をインストールし、Connect-MgGraph -Scopes "Sites.Read.All" を実行して、Get-MgSite -All の出力を CSV にエクスポートしてみてください。そのうえで、次に使うコマンドレットには Find-MgGraphCommand でアクセス許可を確認してから、SharePoint の作業で Microsoft Graph PowerShell を本番環境で使ってください。

番組をフォローSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS