【GraphAPI】Graph Explorer  (1)：基本的な使い方

# はじめに

Graph Explorer を使うと、ユーザー委任権限で Graph API を簡単に実行することができます。Graph Explorer を初めて使う方向けに、手順をまとめました。

# Graph Explorer へのアクセス

Graph Explorer は、ブラウザから以下の URL にアクセスして使用します。
https://developer.microsoft.com/en-us/graph/graph-explorer

# 1. Graph API を実行する

## 1.1 サインイン

最初に、右上の **[Sign in]** ボタンから、任意のユーザーでサインインを行います。
※ サインインするユーザーは管理者権限の無い一般ユーザーで構いません。

::: note
Graph Explorer は [ユーザー委任権限](https://qiita.com/atsmin77/items/31df2f5624840b45dda0#%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E5%A7%94%E4%BB%BB%E6%A8%A9%E9%99%90) で Graph API を実行します。そのため、ユーザーのサインインが必要です。
:::

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/216675dd-60b6-4912-acf9-75dfb195718e.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/d70c6948-c295-4374-a82b-fd82eab8f45c.png)

## 1.2 Graph API の実行

サインインしたら、次に **[Run query]** というボタンをクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/37646283-21ee-4177-b1e5-0c31d5bebe2b.png)

画面中央に **[OK - 200]** と表示され、サインインしたユーザーの情報が Graph API で取得され、画面下の **[Response preview]** に表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/03b77275-17bd-4447-b168-30e1d435274f.png)

::: note
ユーザーの UPN や姓名、メールアドレスが [JSON]() データで取得できていることが分かります。Graph API では、アプリケーションが処理しやすいようにデータは JSON 形式で取得されます。 
:::

## 1.3 補足

画面上部に注目すると、以下のような URL が既定で入力されています。

```
https://graph.microsoft.com/v1.0/me
```

これは、サインインしたユーザーの情報を取得する Graph API の URL です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/711d5359-9250-4cf7-9f18-0c0d94318656.png)

ユーザーの情報を取得する Graph API については、以下の公開情報に記載されています。

(参考：ユーザーの取得)
https://learn.microsoft.com/ja-jp/graph/api/user-get?view=graph-rest-1.0&tabs=http
> HTTP 要求
> GET /me

::: note
公開情報の [HTTP 要求] 欄に Graph API の URL で指定する内容が記載されています。先頭の "https://graph.microsoft.com/v1.0" は共通なので省略されています。
:::

<ins>様々な操作を行うための Graph API が用意されています。行いたい操作に応じて公開情報のとおりに URL を変更します</ins>。

次に、例としてサインインしたユーザーが所属する Teams のチーム一覧を Graph API で取得してみます。

# 2. チームの一覧情報を取得する

## 2.1 URL の変更

チームの一覧を取得する Graph API の公開情報には以下のように記載されています。

(参考：チームの一覧表示)
https://learn.microsoft.com/ja-jp/graph/api/teams-list?view=graph-rest-1.0&tabs=http
> HTTP 要求
> GET /teams

公開情報のとおり、URL の **"/me"** を **"/teams"** に変更します。

```
https://graph.microsoft.com/v1.0/teams
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/93de5451-66c3-4b93-9cb3-37c93d60298a.png)

再度、**[Run query]** から Graph API を実行してみます。今度は、画面中央に **[Forbidden - 403]** と表示され、情報の取得が行えません。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/0a10dcdd-6ee5-4617-a931-806721ae1e5d.png)

**[Response preview]** をよく見ると、以下のメッセージが表示されています。
>"message": "Missing scope permissions on the request...

これは Graph Explorer に対してアクセス許可を付与していないことが原因です。

1 で実行したユーザーの情報を取得する API は既定でアクセスが許可されているため、エラーになりませんでした。

しかし、<ins>Graph API では一般的に既定でアクセスが許可されていないため、実行する前にアクセスを許可する必要があります</ins>。

#### HTTP ステータスコード

::: note
[OK-**200**] や [Forbidden-**403**] などの 3 桁の数字は HTTP ステータスコードです。
200 や 201 といった 2 から始まるコード (**2xx**) であれば正常に Graph API が実行できています。
:::

(参考：IIS での HTTP 状態コード)
https://learn.microsoft.com/ja-jp/troubleshoot/developer/webapps/iis/health-diagnostic-performance/http-status-code

## 2.2 アクセス許可の付与

アクセス許可は **[Modify Permissions]** タブから付与することができます。

[Modify Permissions] タブをクリックすると、URL に入力した Graph API を実行するために必要なアクセス許可が表示されます。

**[Team.ReadBasic.All]** がアクセス許可の名前です。**[Consent]** ボタンをクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/60d965f9-bfeb-4c25-b398-4bbe232967ae.png)

以下のダイアログが表示されます。**[Accept]** ボタンをクリックすると、Graph Explorer にアクセス許可が付与されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/94b9bd98-2b28-4a52-aed9-ef2dea46b55f.png)

::: note warn
以下のダイアログが表示された場合は、Graph API を利用するために**管理者の同意**が必要となるよう、[テナントの設定](https://qiita.com/atsmin77/items/b6bd8def4b9ddc5ab49b#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E8%A8%B1%E5%8F%AF%E3%81%A7%E7%AE%A1%E7%90%86%E8%80%85%E3%81%AE%E5%90%8C%E6%84%8F%E3%82%92%E5%BF%85%E8%A6%81%E3%81%A8%E3%81%99%E3%82%8B%E6%96%B9%E6%B3%95)によって制御されています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/6c8509cf-1bc0-44a2-9610-f998a0e04d83.png)
:::

正常にアクセス許可が付与されると、画面中央に **[Success]** と表示され、ボタンが **[Unconsent]** に変わります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/47797eb1-5653-43ce-a758-15a0560060a7.png)

この状態で再度 **[Run query]** を実行すると、今度は正常にチームの情報が取得されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/4231807c-d413-4d85-898d-7acd8614d570.png)

## 2.3 補足
### ページングについて

Graph API では一度の実行で取得できるデータの件数に上限があります。上限を超えるデータをすべて取得する場合には、複数回 Graph API を実行する必要があります。

::: note
このような処理を **"ページング"** と呼びます。長い記事の Web サイトで <[1][2][3]...> と各ページのリンクをクリックして 1 ページずつ内容を読むのと同じです。
:::

チームの一覧情報を取得する Graph API では、一度の実行で 100 件のチームまで取得することができます。

上限のためすべての情報を取得できなかった場合には、取得した結果に **"@odata.nextLink"** が含まれています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/5f515217-80bf-4bd3-9f6b-940771b66578.png)

"@odata.nextLink" には、以下のような URL が記載されています。

```
https://graph.microsoft.com/v1.0/teams?$skiptoken=xxx...
```

この URL を使用して再度 [Run query] から Graph API を実行すると、残りの情報を取得することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/73ab3dd3-b43b-4051-9ecb-f65e700bc480.png)

::: note
すべての情報が取得できた場合には、取得結果に "@odata.nextLink" が含まれません。
"@odata.nextLink" が返されなくなるまで繰り返し Graph API を実行することで、すべての情報を取得することができます。
:::

(参考：アプリで Microsoft Graph データをページングする)
https://learn.microsoft.com/ja-jp/graph/paging?tabs=http

### アクセス許可について
必要なアクセス許可は Graph API ごとに異なります。各 Graph API の公開情報で **[アクセス許可]** のセクションに必要なアクセス許可が記載されています。

ユーザー委任権限で Graph API を実行する場合は、**[委任 (職場または学校のアカウント)]** の行を確認します。

（参考：チームの一覧表示）
https://learn.microsoft.com/ja-jp/graph/api/teams-list?view=graph-rest-1.0&tabs=http#permissions
> アクセス許可
>| アクセス許可の種類 | 最小特権アクセス許可 | より高い特権のアクセス許可 |
>|:-:|:-:|:-:|
>| 委任 (職場または学校のアカウント) | Team.ReadBasic.All | TeamSettings.Read.All、TeamSettings.ReadWrite.All |

アクセス許可には、[最小特権アクセス許可] と [より高い特権のアクセス許可] が記載されています。特別な理由が無ければ、最小特権のアクセス許可を利用します。

(参考：最小特権の原則を実装する)
https://learn.microsoft.com/ja-jp/graph/best-practices-graph-permission#implement-the-principle-of-least-privilege

#### 最小特権アクセス許可
該当する Graph API を実行するための最小限のアクセス権限です。
■ 例
Team.ReadBasic.All：チームの名前や説明といった情報のみにアクセスできる権限です。

#### より高い特権のアクセス許可
より強いアクセス権限です。該当する Graph API 以外の API も実行できる場合があります。
■ 例
TeamSettings.ReadWrite.All：チームの名前や説明のほか、チームの設定情報の読み取りや変更が行える権限です。

::: note
各アクセス許可で行える操作については、以下の公開情報に記載されています。
（参考：Microsoft Graph のアクセス許可のリファレンス）
https://learn.microsoft.com/ja-jp/graph/permissions-reference
:::

# 3. チームを作成する

次に、Graph API からチームを作成してみます。

以下のチームを作成する Graph API の公開情報を基に URL の変更やアクセス許可の付与を行います。
(参考：チームを作成する)
https://learn.microsoft.com/ja-jp/graph/api/team-post?view=graph-rest-1.0&tabs=http

## 3.1 URL の変更

公開情報を確認すると、以下のように記載されています。

>HTTP 要求
>POST /teams

**"/teams"** は 2 のチーム一覧取得 Graph API と同じです。しかし、チーム一覧取得 Graph APIの場合には、**"GET"** でしたが、今度は **"POST"** と表記されています。

この場合には、以下のプルダウンから **[POST]** に変更します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/41f44c64-b266-4df8-8930-59f5bc00b6ca.png)

::: note
"GET" や "POST" は **HTTP リクエスト メソッド** です。データに対して行う操作によって以下の 5 つから選択します。
:::
| HTTP リクエスト メソッド | 操作 |
|:-:|:-:|
| GET | 取得 |
| POST | 登録 |
| PUT/PATCH | 変更 |
| DELETE | 削除 |

## 3.2 送信データの設定

チームを作成する場合など、データの登録や変更を行う場合にはチーム名などの情報を送信データとして設定する必要があります。
送信データは JSON 形式で指定します。どのように指定すれば良いのかは公開情報に例が記載されています。

(参考：例 1: 委任されたアクセス許可)
https://learn.microsoft.com/ja-jp/graph/api/team-post?view=graph-rest-1.0&tabs=http#example-1-delegated-permissions
>{
>  "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",
>}

| 設定箇所 | 意味 |
|:-:|:-:|
| displayName | チーム名 |
| description | 説明 |
| firstChannelName | 最初のチャネルの名前 |

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

```
{
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName": "テストチーム01",
  "description": "Graph API から作成したテストチームです。",
  "firstChannelName": "テストチャネル01",
}
```
送信データは **[Request Body]** タブで設定します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/645695e8-76f5-47af-b897-508db521efe5.png)

::: note
チャネルやチームに既定でインストールするアプリなどの細かな指定も行えます。公開情報に例が載っています。
:::
(参考：例 3: 委任されたアクセス許可を使用して、複数のチャネル、インストールされたアプリ、および固定されたタブを持つチームを作成する)
https://learn.microsoft.com/ja-jp/graph/api/team-post?view=graph-rest-1.0&tabs=http#example-3-create-a-team-with-multiple-channels-installed-apps-and-pinned-tabs-using-delegated-permissions

## 3.3 アクセス許可の付与

[2.2](#22-アクセス許可の付与) と同様にアクセス許可を付与します。Graph API からチームを作成するために必要な最小特権アクセス許可は **"Team.Create"** です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/9002acc0-bc6f-469c-b0eb-53bc4f808bf1.png)

**[Run query]** をクリックすると、Graph API が実行されます。正常に実行されると、画面中央に **[Accepted - 202]** と表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/37abd06f-c14f-4629-80f4-50b6b914066e.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2680397/0841b788-ac90-4572-936b-abf415bef3be.png)

::: note
Graph Explorer にサインインしたユーザーが既定でチームの所有者として設定されます。
:::

# 次の記事

今度は、作成したチームにユーザーを追加してみます。以下の記事に続きます。


https://qiita.com/atsmin77/private/b6bd8def4b9ddc5ab49b

::: note
ここまでの手順は一般ユーザーでも実行することができます。しかし、Graph API でチームにユーザーを追加するには、管理者ロールが付与されたユーザーの同意が必要になります。次回の記事でその手順も紹介しています。
:::