はじめに
Graph PowerShell を利用すると、PowerShell コマンドで Graph API を実行することができます。
この記事では、Graph PowerShell から Graph API を実行する方法とまとめました。
※ Graph PowerShell のインストール方法については以下の記事にあります。
Graph API の実行方法
以下の流れで Graph PowerShell から Graph API を実行します。
- 実行するコマンドの確認
- コマンドの実行
- 認証
- 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