【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] ボタンから、任意のユーザーでサインインを行います。
※ サインインするユーザーは管理者権限の無い一般ユーザーで構いません。

Graph Explorer は ユーザー委任権限 で Graph API を実行します。そのため、ユーザーのサインインが必要です。

1.2 Graph API の実行

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

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

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

1.3 補足

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

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

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

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

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

HTTP 要求
GET /me

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

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

次に、例としてサインインしたユーザーが所属する 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

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

[Response preview] をよく見ると、以下のメッセージが表示されています。

"message": "Missing scope permissions on the request...

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

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

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

HTTP ステータスコード

[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] ボタンをクリックします。

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

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

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

2.3 補足

必要なアクセス許可は 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

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

最小特権アクセス許可

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

より高い特権のアクセス許可

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

各アクセス許可で行える操作については、以下の公開情報に記載されています。
（参考：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] に変更します。

"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

{
"[e-mail]": "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	最初のチャネルの名前

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

{
  "[e-mail]": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName": "テストチーム01",
  "description": "Graph API から作成したテストチームです。",
  "firstChannelName": "テストチャネル01",
}

送信データは [Request Body] タブで設定します。

チャネルやチームに既定でインストールするアプリなどの細かな指定も行えます。公開情報に例が載っています。

(参考：例 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 と同様にアクセス許可を付与します。Graph API からチームを作成するために必要な最小特権アクセス許可は "Team.Create" です。

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

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

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

次の記事

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

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