Microsoft Graph を使ってみよう : ユーザーとグループリソース

今回はドキュメントの見方とユーザーとグループリソースの紹介です。

# Microsoft Graph のドキュメント

リソース自体の説明は [ドキュメント](https://developer.microsoft.com/ja-jp/graph/docs/concepts/overview) の **LEARN** セクションを参照。
開発に必要なドキュメントは [v1.0 参照](https://developer.microsoft.com/ja-jp/graph/docs/concepts/v1-overview) または [ベータ参照](https://developer.microsoft.com/ja-jp/graph/docs/api-reference/beta/beta-overview) にあります。

ドキュメントにアクセス後、確認したいリソースを展開して内容を確認してください。一部英語のままであったり、英語のドキュメントが最新の場合もあるため、可能であれば英語のドキュメントを推奨します。

### 例: ユーザーリソース
ここではユーザーリソースについて調べる方法を紹介します。

- [LEARN のユーザセクション](https://developer.microsoft.com/ja-jp/graph/docs/concepts/azuread-users-concept-overview) を確認。LEARN にリソースの概要が記載あり。
- API の詳細は [v1.0 参照](https://developer.microsoft.com/ja-jp/graph/docs/concepts/v1-overview) にアクセス。"v1.0 参照" 直下のユーザー項目にはリソースの操作に必要な権限やプロパティ情報があり、ユーザー配下の各リソースはユーザーから辿れる関連リソースとなっている。例えばユーザーからは予定表や連絡先が辿れることが分かる。

<img width="762" alt="Capture.PNG" src="https://qiita-image-store.s3.amazonaws.com/0/214116/33f845ff-bc91-a0e6-832b-8255f6ea0e9d.png">

- 必要に応じてベータ参照も確認。

# ユーザーリソース

Microsoft Graph のユーザーリソースは Azure Active Directory (Azure AD) またはマイクロソフトアカウントのユーザーを表しており、予定表や連絡先など様々なリソースにリンクしている中心的なリソースです。

<img src="https://cdn.graph.office.net/prod/GraphDocuments\en-us\concepts\images/users.png">

## 主なシナリオ
ユーザーはアプリケーションの中心となることが多いため、シナリオも多岐に渡ります。例)

- ユーザーの作成や削除
- プロファイル写真の取得や更新
- ユーザーが所属するグループ、マネージャーや部下の取得
- 関連する予定やタスク、ドキュメントなどの各種操作
- 空き時間の取得やメールの取得や送信、移動といった操作
- トレンドドキュメントのような動的な情報の取得

### /me 
/me は自ユーザーの URL であり、/users/自身のユーザーID と同等です。

## User リソースの操作
いくつか代表的な操作を以下に紹介します。

**自分の情報を取得**
GET: https://graph.microsoft.com/v1.0/me

```csharp:C#
await graphClient.Me.Request().GetAsync();
```

**プロファイル写真の取得**
GET: https://graph.microsoft.com/v1.0/me/photo/$value

```csharp:C#
await graphClient.Me.Photo.Content.Request().GetAsync();
```
**自分の上司や部下を取得**
GET: https://graph.microsoft.com/v1.0/me/manager
GET: https://graph.microsoft.com/v1.0/me/directReports

```csharp:C#
await graphClient.Me.Manager.Request().GetAsync();
await graphClient.Me.DirectReports.Request().GetAsync();
```

**自分の予定一覧を取得**
GET: https://graph.microsoft.com/v1.0/me/events

```csharp:C#
await graphClient.Me.Events.Request().GetAsync();
```

**会議の候補日時を検索する**
他の参加者や会議室などを指定することも可能。以下の例では 5/20 9 時から 5/21 17 時までで 1 時間空きがある候補を検索。

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

```json:Body
{ 
  "attendees": [ 
  ],  
  "locationConstraint": { 
    "isRequired": "false",  
    "suggestLocation": "false",  
    "locations": [ 
    ] 
  },  
  "timeConstraint": {
    "activityDomain":"unrestricted", 
    "timeslots": [ 
      { 
        "start": { 
          "dateTime": "2018-05-20T09:00:00",  
          "timeZone": "Tokyo Standard Time" 
        },  
        "end": { 
          "dateTime": "2018-05-21T17:00:00",  
          "timeZone": "Tokyo Standard Time" 
        } 
      } 
    ] 
  },  
  "meetingDuration": "PT1H",
  "returnSuggestionReasons": "true",
  "minimumAttendeePercentage": "100"
}
``` 

```csharp:C#
var freeTimes = await graphClient.Me.FindMeetingTimes(
    TimeConstraint: new TimeConstraint()
    {
        ActivityDomain = ActivityDomain.Unrestricted,
        Timeslots = new List<TimeSlot>() {
            new TimeSlot() {
                Start = new DateTimeTimeZone() {
                    DateTime = "2018-05-20T09:00:00",
                    TimeZone = "Tokyo Standard Time"},
                End = new DateTimeTimeZone() {
                    DateTime = "2018-05-21T18:00:00",
                    TimeZone = "Tokyo Standard Time"}
            }
        }
    },
    MeetingDuration: new Duration("PT1H"),
    ReturnSuggestionReasons: true,
    MinimumAttendeePercentage: 100
).Request().PostAsync();
```

# グループ

ユーザーやプリンシパルの集合としてグループを定義するこが出来ます。グループは種類が複数ありますが、Office 365 グループは共同作業のためのグループで、ユーザー同様多くのリソースと関連を持ちます。

<img src="https://cdn.graph.office.net/prod/GraphDocuments\en-us\concepts\images/office365-groups-concept-overview-related-services-infographic.png" alt="Diagram showing Office 365 group integration with files, notes, tasks, sites, conversations, and calendar">

グループに対する操作は管理者レベルの承認が必要となります。

## グループの種類

| 種類      | タイプ | メールが有効 | セキュリティが有効 | API で作成可能 |
| :-- | :-- | :-- | :-- | :-- |
| Office 365 グループ | unified | true | false | はい |
| セキュリティグループ | | false | true | はい |
| メールが有効なセキュリティ グループ | | true | true | いいえ |
| 配布グループ | | true | false | いいえ |


詳細は [グループ](https://developer.microsoft.com/ja-jp/graph/docs/api-reference/v1.0/resources/groups-overview) を参照。

## 動的メンバーシップ
各グループに所属するユーザーは静的追加できますが、条件を指定して動的に管理することも可能です。動的メンバーグループを作る場合、groupType に DynamicMembership を追加し、membershipRule を追加します。
※この機能を利用するには、Azure AD Premium P1 以上のライセンスが必要です。またこの機能は現在ベータ版です。

## 主なシナリオ

グループも本体だけでなく関連リソースが多く、シナリオも多岐に渡ります。例)

- グループの CRUD (作成、取得、更新、削除)
- グループメンバーの表示、追加、削除
- グループ設定やプロファイルの管理
- グループ所有者の表示、追加、削除
- グループの関する予定、会話、スレッド、メモやファイルなど関連リソースの CRUD 
 
## グループリソースの操作

いくつか代表的な操作を以下に紹介します。

**グループの情報を取得**
GET: https://graph.microsoft.com/v1.0/groups
GET: https://graph.microsoft.com/v1.0/groups/{id}

```csharp:C#
await graphClient.Groups.Request().GetAsync();
await graphClient.Groups["id"].Request().GetAsync();
```
**グループにメンバーを追加**
URL の id にグループの ID を、Body の id にグループに追加するユーザーやグループの ID を指定。

POST https://graph.microsoft.com/v1.0/groups/{id}/members/$ref

```json:Body
{
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}
```

```csharp:C#
var userToAdd = await graphClient.Users["id"].Request().GetAsync();
await graphClient.Groups["id"].Members.References.Request().AddAsync(userToAdd);
```
**メンバーの一覧を取得**
GET https://graph.microsoft.com/v1.0/groups/{id}/members

```csharp:C#
await graphClient.Groups["id"].Members.Request().GetAsync();
```
**グループ内のスレッド、イベントやファイル、ノートブックのページを取得**

GET https://graph.microsoft.com/v1.0/groups/{id}/conversations
GET https://graph.microsoft.com/v1.0/groups/{id}/events
GET https://graph.microsoft.com/v1.0/groups/{id}/drive/root/children
GET https://graph.microsoft.com/v1.0/groups/{id}/onenote/pages

```csharp:C#
await graphClient.Groups["id"].Conversations.Request().GetAsync();
await graphClient.Groups["id"].Drive.Root.Children.Request().GetAsync();
await graphClient.Groups["id"].Events.Request().GetAsync();
await graphClient.Groups["id"].Onenote.Pages.Request().GetAsync();
```

# まとめ
ユーザーとグループは多くの処理の軸となるため、まずこれらを使いこなせるよう色々と試してください。

[目次へ戻る](https://qiita.com/kenakamu/items/6a1ca508dc093779eefa)

# 参照

[Microsoft Graph でのユーザーの操作](https://developer.microsoft.com/ja-jp/graph/docs/api-reference/v1.0/resources/users)
[Microsoft Graph でのグループの操作](https://developer.microsoft.com/ja-jp/graph/docs/api-reference/v1.0/resources/groups-overview)