【GraphAPI】Graph PowerShell (4)：Graph API の実行

# はじめに

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

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

https://qiita.com/atsmin77/private/264d10bd9d7e9dfeaace

# Graph API の実行方法

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

1. 実行するコマンドの確認
1. コマンドの実行
   1. 認証
   1. 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 を指定します。

```powershell
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…
```

※ 実行結果には [ベータ版モジュール](https://qiita.com/atsmin77/private/264d10bd9d7e9dfeaace#%E3%83%99%E3%83%BC%E3%82%BF%E7%89%88%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB) のコマンドも併せて表示されます。
正式版モジュールのコマンドのみを表示するには以下のようにします。

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

::: note
Graph PowerShell のコマンドから、そのコマンドが実行する Graph API の URI や必要なアクセス許可を確認することもできます。"-Command" に Graph PowerShell のコマンドを指定します。
:::

```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 コマンドを実行します。

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

* ユーザー委任権限

https://qiita.com/atsmin77/private/09162cffd26618c8083f

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

https://qiita.com/atsmin77/private/6bcc9fb88b305e124399

### 2.2 Graph API の実行

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

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

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

```powershell
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.…
...
```

::: note
Graph PowerShell では **"-All"** をつけて実行することですべての情報を取得することができます。
"-All" をつけて実行すると、[ページング](https://qiita.com/atsmin77/items/a1d53031b120da5d9697#%E3%83%9A%E3%83%BC%E3%82%B8%E3%83%B3%E3%82%B0%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6) 処理によって情報がすべて取得されるまで、自動的に繰り返し Graph API が実行されます。
:::

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

```
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

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

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

New-MgTeam -BodyParameter $params
```

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/5d4c1bf0-f44f-4c0e-a20f-ecc9c88b558d.png)

::: note warn
Graph PowerShell の "-BodyParameter" は PowerShell の [ハッシュテーブル](https://learn.microsoft.com/ja-jp/powershell/scripting/learn/deep-dives/everything-about-hashtable?view=powershell-7.5) の形式で指定します。
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 を実行することができます。

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

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

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

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

::: note warn
Get-MgUser 等のコマンドと異なり、取得された情報は "value" に含まれています。
:::

##### 実行例 2：チームの作成

```powershell
$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