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

Microsoft Graph のドキュメント

リソース自体の説明はドキュメントの LEARN セクションを参照。
開発に必要なドキュメントは v1.0 参照またはベータ参照にあります。

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

例: ユーザーリソース

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

LEARN のユーザセクションを確認。LEARN にリソースの概要が記載あり。
API の詳細は v1.0 参照にアクセス。"v1.0 参照" 直下のユーザー項目にはリソースの操作に必要な権限やプロパティ情報があり、ユーザー配下の各リソースはユーザーから辿れる関連リソースとなっている。例えばユーザーからは予定表や連絡先が辿れることが分かる。

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

ユーザーリソース

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

主なシナリオ

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

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

/me

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

User リソースの操作

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

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

C#

await graphClient.Me.Request().GetAsync();

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

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

C#

await graphClient.Me.Manager.Request().GetAsync();
await graphClient.Me.DirectReports.Request().GetAsync();

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

C#

await graphClient.Me.Events.Request().GetAsync();

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

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

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"
}

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 グループは共同作業のためのグループで、ユーザー同様多くのリソースと関連を持ちます。

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	いいえ

詳細はグループを参照。

動的メンバーシップ

各グループに所属するユーザーは静的追加できますが、条件を指定して動的に管理することも可能です。動的メンバーグループを作る場合、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}

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

Body

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

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

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

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();

まとめ

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

目次へ戻る

参照

Microsoft Graph でのユーザーの操作
 Microsoft Graph でのグループの操作