はじめに

Graph PowerShell を利用すると、PowerShell コマンドで Graph API を実行することができます。
この記事では、Graph PowerShell から Graph API を実行する方法とまとめました。

※ Graph PowerShell のインストール方法については以下の記事にあります。

Graph API の実行方法

以下の流れで Graph PowerShell から Graph API を実行します。

実行するコマンドの確認
コマンドの実行
1. 認証
2. Graph API の実行

1. 実行するコマンドの確認

Find-MgGraphCommand コマンド

Find-MgGraphCommand コマンドを利用すると、特定の Graph API を実行するために、どのコマンドを使用すればよいのかを調べることができます。

例えば、ユーザー情報一覧取得 Graph API の URI は "/users" です。

(参考：ユーザーを一覧表示する)
https://learn.microsoft.com/ja-jp/graph/api/user-list?view=graph-rest-1.0&tabs=http

HTTP 要求
GET /users

この Graph API に関する Graph PowerShell のコマンドを調べるには、以下のコマンドを実行します。"-Uri" に Graph API の URI を指定します。

Find-MgGraphCommand -Uri "/users"

※ 実行結果

   APIVersion: v1.0

Command    Module Method URI    OutputType          Permissions
-------    ------ ------ ---    ----------          -----------
Get-MgUser Users  GET    /users IMicrosoftGraphUser {User.ReadBasic.All, User.ReadBasic.All, User.ReadWrite.All, Devic…
New-MgUser Users  POST   /users IMicrosoftGraphUser {User.ReadWrite.All, User.ReadWrite.All, Directory.ReadWrite.All, …

   APIVersion: beta

Command        Module     Method URI    OutputType          Permissions
-------        ------     ------ ---    ----------          -----------
Get-MgBetaUser Beta.Users GET    /users IMicrosoftGraphUser {User.ReadBasic.All, User.ReadBasic.All, User.ReadWrite.Al…
New-MgBetaUser Beta.Users POST   /users IMicrosoftGraphUser {User.ReadWrite.All, User.ReadWrite.All, Directory.ReadWri…

※ 実行結果にはベータ版モジュールのコマンドも併せて表示されます。
正式版モジュールのコマンドのみを表示するには以下のようにします。

Find-MgGraphCommand -Uri "/users" -ApiVersion "v1.0"

Graph PowerShell のコマンドから、そのコマンドが実行する Graph API を確認することもできます。"-Command" に Graph PowerShell のコマンドを指定します。

Find-MgGraphCommand -Command "Get-MgUser"

※ 実行結果

   APIVersion: v1.0

Command    Module Method URI              OutputType          Permissions
-------    ------ ------ ---              ----------          -----------
Get-MgUser Users  GET    /users/{user-id} IMicrosoftGraphUser {User.Read, User.ReadBasic.All, User.ReadBasic.All, Devi…
Get-MgUser Users  GET    /users           IMicrosoftGraphUser {User.ReadBasic.All, User.ReadBasic.All, User.ReadWrite.…

(参考：Using Find-MgGraphCommand cmdlet)
https://learn.microsoft.com/en-us/powershell/microsoftgraph/find-mg-graph-command?view=graph-powershell-1.0

2. コマンドの実行

2.1 認証

最初に、ユーザー委任権限、またはアプリケーション許可権限で Connect-MgGraph コマンドを実行します。

※ 各実行方法についての記事はこちらです。

ユーザー委任権限

アプリケーション許可権限

2.2 Graph API の実行

認証が正常に完了したら、Graph PowerShell のコマンドから Graph API を実行することができます。

実行例 1：ユーザー情報の取得

例えば Get-MgUser コマンドは Graph API でユーザー情報を取得するコマンドです。

Get-MgUser -All

コマンドを実行すると、アクセスが許可されていれば正常に結果が返されます。

※ 実行結果の例

DisplayName        Id                                   Mail                                        UserPrincipalName
-----------        --                                   ----                                        -----------------
テスト ユーザー01  c1fe9cb2-87f9-4a6a-b040-a5b63108dc4e testuser01@atsmin.net                       testuser01@atsmin.…
テスト ユーザー02  0963c34e-f94e-49cf-bab8-b6b620fdb66f testuser02@atsmin.net                       testuser02@atsmin.…
テスト ユーザー03  ecd80e02-bc39-461e-a7dc-c9a749db27a9 testuser03@atsmin.net                       testuser03@atsmin.…
...

Graph PowerShell では "-All" をつけて実行することですべての情報を取得することができます。
"-All" をつけて実行すると、ページング処理によって情報がすべて取得されるまで、自動的に繰り返し Graph API が実行されます。

アクセスが許可されていない場合には、以下のようなエラーメッセージが表示されます。

Missing scope permissions on the request. API requires one of...
...
Status: 403 (Forbidden)
ErrorCode: Forbidden

(参考：Get-MgUser)
https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.users/get-mguser?view=graph-powershell-1.0

実行例 2：チームの作成

New-MgTeam コマンドは Graph API でチームを作成するコマンドです。このようなコマンドの場合は、チームの名前などの情報を "-BodyParameter" で指定する必要があります。

公開情報に例が記載されています。

(参考：New-MgTeam)
https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.teams/new-mgteam?view=graph-powershell-1.0#example-1-code-snippet

Import-Module Microsoft.Graph.Teams

$params = @{
"template@odata.bind" = "https://graph.microsoft.com/v1.0/teamsTemplates('standard')"
displayName = "My Sample Team"
description = "My sample team’s description"
firstChannelName = "My first channel of the sample team"
}

New-MgTeam -BodyParameter $params

例えば、以下のように指定します。

$params = @{
  "template@odata.bind" = "https://graph.microsoft.com/v1.0/teamsTemplates('standard')"
  "displayName" = "テストチーム03"
  "description" = "Graph PowerShell から作成したテストチームです。"
  "firstChannelName" = "テストチャネル01"
}

New-MgTeam -BodyParameter $params

コマンド実行後、Teams クライアントからチームが作成されていることを確認できます。

Graph PowerShell の "-BodyParameter" は PowerShell のハッシュテーブルの形式で指定します。
Graph API の公開情報に記載されている JSON 形式とは以下の点が異なるので注意が必要です。

コロン (":") ではなくてイコール ("=") を使う
末尾にカンマ (",") が無い

■ Graph PowerShell の場合

$params = @{
"template@odata.bind" = "https://graph.microsoft.com/v1.0/teamsTemplates('standard')"
displayName = "My Sample Team"
description = "My sample team’s description"
firstChannelName = "My first channel of the sample team"
}

■ Graph API の場合

{
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"displayName": "My Sample Team",
"description": "My sample team’s description",
"firstChannelName": "My first channel of the sample team",
}

(参考：例 1: 委任されたアクセス許可)
https://learn.microsoft.com/ja-jp/graph/api/team-post?view=graph-rest-1.0&tabs=http#request

補足

Invoke-MgGraphRequest コマンド

Graph PowerShell から Graph API を実行するには Invoke-MgGraphRequest コマンドも利用できます。

Invoke-MgGraphRequest は各 Graph API を実行するための汎用的なコマンドです。実行したい Graph API に対応する Graph PowerShell のコマンドが無い場合でも Graph API を実行することができます。

Invoke-MgGraphRequest は "Microsoft.Graph.Authentication" モジュールに含まれているため、このモジュールをインストールすれば使用できます。

Invoke-MgGraphRequest では実行したい Graph API の "-Method" と "-Uri" を指定します。Graph API の公開情報の [HTTP 要求] セクションを参考にして指定します。

実行例 1：ユーザー情報の取得

$result = Invoke-MgGraphRequest -Method GET -Uri "/v1.0/users" -OutputType PSObject
$result.value | ft DisplayName, Id, Mail, UserPrincipalName

Get-MgUser と異なり、取得された情報は "value" に含まれています。

実行例 2：チームの作成

$params = @{
  "template@odata.bind" = "https://graph.microsoft.com/v1.0/teamsTemplates('standard')"
  "displayName" = "テストチーム03"
  "description" = "Graph PowerShell から作成したテストチームです。"
  "firstChannelName" = "テストチャネル01"
}

Invoke-MgGraphRequest -Method POST -Uri "/v1.0/teams" -Body $params

(参考：Invoke-MgGraphRequest)
https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.authentication/invoke-mggraphrequest?view=graph-powershell-1.0