2015/11 追記 :
Microsoft Graph API は GA (General Availability) されました。サービス提供をされる際は、下記のエンドポイントの URL を https://graph.microsoft.com/beta/ から https://graph.microsoft.com/{api version}/ (https://graph.microsoft.com/v1.0/ など) に変更してください。

こんにちは。

従来 Office 365 における API は、OneDrive REST API、Outlook REST API など製品ごとに分散し、また、OneDrive API と OneDrive for Business API など、その歴史的経緯から一般向けサービスとビジネス向けサービスの間でも異なる API を使用してきました。
これからは、API の世界では、こうした製品間やブランド間 (一般向けとビジネス向けの間) の垣根は無くなります。
ここで述べる Microsoft Graph (旧 Office 365 unified api) によって、Exchange、SharePoint、OneDrive for Business などの Office 365 の各サービス、さらにはセキュリティ、デバイス管理 (Intune)、デバイス上での Activity なども含めて、製品をまたがった参照や操作が、1 つの直観的なパス (URI) を使って可能になります。

例えば、自分のドキュメントの中で最後に更新されたファイルの更新者を確認し、その更新者の上司にメールを送信する場合、これを従来の分散化された API (Office 365 API 参照) で実装する場合は、OneDrive REST API、Office Graph REST API、Outlook REST API の 3 種類のエンドポイントを呼び出す必要がありましたが、Microsoft Graph では単一の Endpoint に対する操作で実装できます。開発者にとって下記のメリットがあります。(具体的な API の使い方については後述します。)

• リソースごとの Access Token の取り直しが不要です
• 例えば、File Handler のように、製品横断のさまざまなシナリオを横断的にサポートできます (利用者は OneDrive、Outlook など複数製品からファイルを選択する可能性があり、従来の API では個別に Permission 設定などをおこなう必要があります)

なお、現時点では従来型の Office 365 API (Outlook REST API, OneDrive API など) との間に多数の機能差もあり、必要に応じて以前の API を使わなければならないケースもありますが、Microsoft Graph の機能は今後も拡張されていきます。(また新機能の多くも、Microsoft Graph に投資されていくことになります。)

すべてをまとめる API

Microsoft Graph では、outlook.com などの Consumer 側 (一般ユーザー側) の Office や、Azure AD そのものも対象としており、Microsoft が提供する SaaS サービス全体の統一的エンドポイントとして進化しています。

一般の Office 365 サービス (Outlook, OneDrive, Teams など) に対する操作以外に、以下の操作も可能です。

• クラウド上の Excel
  Excel REST API を使用して、Office 365 (OneDrive for Business, SharePoint Online) に保存された Excel Workbook に対し、OAuth / REST を介して、ワークシート上のデータ管理 (読み込み / 書き込み)、関数による計算、レポート (Chart など) の取得、Worksheet Automation が可能です。(SharePoint にもともとあった Excel Services と同様のコンセプトです。)
• Azure Active Directory
  User, Group 連携や Azure AD の管理タスクの実行など、従来 Azure AD Graph API でおこなっていた処理が Microsoft Graph に統合されています。
• Administrative Units
  例えば、ある組織における Region ごとの管理者など、階層化された管理ユニット (Administrative Unit) を作成することで、ユーザーの作成・削除、パスワードリセットなどの管理作業を各管理ユニットの管理者に委譲できます。
• Reporting
  Office 365 ダッシュボードで提供している Audit 情報を API で取得できます。
• Identity Protection
  Azure AD Identity Protection が自動検出したユーザーや危険なサインインの情報を API を使って取得できます。
• Intune
  Intune が新しい Azure Portal (コードネーム Ibiza) に統合されるのとあわせて、Microsoft Graph 上からデバイス構成やアプリケーションの管理をおこなえるようになります。Intune の管理作業の自動化で使用できます。
• Activity (Codename : Project Rome)
  PC やモバイルデバイスにおける活動内容の履歴の参照と更新が可能です。「以前使った・・・を再度確認したい」といったケースで、この Activity の履歴を参照できます。
  モバイル デバイス側は、Microsoft が提供するアプリ以外に、Project Rome SDK for iOS または Android を使用してカスタム アプリ (3rd party のアプリ) からも連携できます。

Office 365 の機械学習に基づく Insights API (/me/insights, 自分に関係のあるアイテム)、People API (/me/people, 自分と関係の深い人) も Microsoft Graph で使えます。
例えば、下記は、自分に関係の深いアイテム (ドキュメントなど) を優先順位付で取得しています。

https://graph.microsoft.com/beta/me/insights/trending

Microsoft Graph の使い方

使い方は、いままでと同じです。OAuth Flow で access token を取得し、取得した access token を HTTP Header に付与して https://graph.microsoft.com に HTTP Request を投げるだけです。
この HTTP Flow の詳細は「Office 365 API 入門」を参照してください。

この際、Azure AD (Azure Active Directory) に設定する Application の Permission は「Microsoft Graph」の 1 つで OK です。(下図)
使用する resource name は https://graph.microsoft.com です。

これまでの API だと、refresh token を使って、SharePoint REST API 用の access token, Outlook REST API 用の access token など、resource ごとの access token を取得する必要がありましたが、単一の resource のため、access token の取り直しも不要です。

なお、Microsoft Graph は Azure AD v2 endpoint にも対応しています。Azure AD v2 endpoint を使用した OAuth の Flow については「Azure AD v2.0 endpoint の OAuth を使った Client 開発」を参照してください。現在、Microsoft Account を使用して、Outlook.com (旧 Hotmail) と OneDirve (旧 SkyDrive), OneNote の処理が可能です。

URI の構造

以下に URI の構造を説明します。
ここで紹介する内容は、下記の Microsoft Graph (Unified API) Explorer を使ってすぐに試せますので、実際に API Explorer で入力しながら試してみてください。

Microsoft Graph Explorer
https://developer.microsoft.com/en-us/graph/graph-explorer
(Office 365 のアカウントでログインしてください)

困ったら API Metadata を確認しよう !

これは Microsoft Graph に限った話ではありませんが、API の仕様がわからない時には API metadata を確認しましょう。

https://graph.microsoft.com/beta/$metadata

API metadata には、後述する Entity, Navigation Property, Action, 使用可能な OData query など、多くの仕様が記述されています。
特に Microsoft Graph では、扱うオブジェクトの型も多く、型どうしの関係も多岐に及ぶため、困ったら API metadata を見て確認する癖をつけておくと良いでしょう。

Entity と Entity Set

Microsoft Graph が扱うオブジェクトは、User, Group, Message, Event, Folder, File, Conversation などのいわゆる型 (Type) を持った Entity であり、Entity の集合として Entity Set が使用できます。(使用可能な Entity や Entity Set は、上述の API metadata に記述されています。)

そして、Microsoft Graph の Endpoint は、https://graph.microsoft.com/{api version}/{tenant} に、下記の Tenant-level Resource Collection (いずれか) を指定した Entity Set から始まります。(Tenant-level Resource Collection も、同じく上述の API metadata に記述されています。)

• applications
• contacts
• deviceConfiguration
• devices
• directoryObjects
• directoryRoles
• directoryRoleTemplates
• drives
• groups
• oauth2PermissionGrants
• servicePrincipals
• subscribedSkus
• tenantDetails
• users

例えば、o365demo01.onmicrosoft.com の tenant の場合、user 一覧 (Entity Set) は下記 URI で取得できます。

https://graph.microsoft.com/beta/o365demo01.onmicrosoft.com/users

作成済の Office 365 Group の一覧 (Entity Set) は下記 URI で取得できます。

https://graph.microsoft.com/beta/o365demo01.onmicrosoft.com/groups

また、上記の Entity Set に id を付与した https://graph.microsoft.com/{api version}/{tenant}/{entity-set}/{id} の形式で固有の Entity (インスタンス) を取得できます。(id 属性の値は、取得した Entity Set に記述されています。)
例えば、下記は demouser01@o365demo01.onmicrosoft.com の User Entity を取得します。(User については guid 形式の id 以外に、下記の通り userPrincipalName (UPN) も使用できます。)

https://graph.microsoft.com/beta/o365demo01.onmicrosoft.com/users/demouser01@o365demo01.onmicrosoft.com

Microsoft Graph では「自分の tenant」と「自分自身 (User)」を、下記の Alias (myOrganization, me) を使って表記することもできます。

https://graph.microsoft.com/beta/myOrganization/users

(※上記は https://graph.microsoft.com/beta/
o365demo01.onmicrosoft.com/users と同じ意味です)

https://graph.microsoft.com/beta/me

(※上記は https://graph.microsoft.com/beta/
o365demo01.onmicrosoft.com/users/{id of login user} と同じ意味です)

Property

例えば、https://graph.microsoft.com/beta/me では、下記の HTTP Response (の中の Body) が返ります。
この displayName, mail, city などの 1 つ 1 つを Property と呼びます。

{ "@odata.context": "https://graph.microsoft.com/beta/o365demo01.onmicrosoft.com/$metadata#users/$entity", "@odata.type": "#Microsoft.Graph.User", "@odata.id": "users/234ddd85-8988-4335-a4a5-5b63fe5652b8", "objectType": "User", "objectId": "234ddd85-8988-4335-a4a5-5b63fe5652b8", "userPrincipalName": "tsmatsuz@o365demo01.onmicrosoft.com", "displayName": "Tsuyoshi Matsuzaki", "mail": "tsmatsuz@o365demo01.onmicrosoft.com", "city": "Kokubunji-City", . . .}

Property にも型 (Type) がありますが、Entity と異なり、Primitive Type (string など) か Complex Type です。(つまり、継承不可能な Edge Type です。)
このため、Property に対して、後述する Navigation Property による連鎖や Action は呼び出せないので注意してください。

Navigation Property

関係 (relationship) を表現する Navigation Property を使って、特定の Entity から別の Entity や Entity Set を取得できます。(各 Entity で使用可能な Navigation Property は、上述の API metadata に記述されています。)

例えば、User Entity には、drive, manager, Messages などの Navigation Proprty が定義されていて、下記のような Entity (または Entity Set) を返します。

https://graph.microsoft.com/beta/me/drive

• 自分の OneDrive for Business の情報を取得する
• returns: Microsoft.Graph.drive

https://graph.microsoft.com/beta/me/manager

• 自分の上長 (もし居れば) を取得する
• returns: Microsoft.Graph.DirectoryObject

https://graph.microsoft.com/beta/me/Messages

• 自分の Message (メール) を取得する
• returns: Collection(Microsoft.Graph.Message)

Entity から Entity を取得できるため、Navigation Property の連鎖も可能です。
例えば、以下は、Navigation Property の drive で得られた Microsoft.Graph.drive から、さらにその Navigation Property である root を呼び出し、ルート フォルダー (Microsoft.Graph.item 型) を取得しています。

https://graph.microsoft.com/beta/me/drive/root

なお、Folder 内の Item (Folder / File) を取得する場合は、Microsoft.Graph.item の Navigation Property である children を使用します。
下記はルート フォルダー下の Item (Folder / File) の一覧を取得します。

https://graph.microsoft.com/beta/me/drive/root/children

上記で取得した Item を個別に取得するには、下記の通り、drive の Navigation Property である items を使用してください。(下記の {id of item} には、上記で取得した item の id プロパティの値を設定します。)

https://graph.microsoft.com/beta/me/drive/items/{id of item}

戻り値で定義された Entity にない Navigation Property や Action は呼び出せないので注意してください。

例えば、上記で取得した item (file など) の最終更新者の上長は、下記で取得できます。

https://graph.microsoft.com/beta/me/drive/items/{id of item}/lastModifiedByUser/manager

ところが、下記 (その上長の取得) は Error になります。
User の Navigation Property “manager” は、ほとんどの場合 User 情報を返しますが、上述の通り戻り値の型定義 (Returned Type Definition) は User 型の BaseType である DirectoryObject 型であるためです。(DirectoryObject に Navigation Property “manager” は存在しません。)

https://graph.microsoft.com/beta/me/drive/items/{id of item}/lastModifiedByUser/manager/manager(This is error !)

補足 : こうした場合、DirectoryObject から User への Cast ができれば良いのですが、Typecasting は Microsoft Graph API (Unified API) beta では提供されていません。
現 beta では、objectId (または upn) を取得して User Entity を取り直してください。(現状は、2 度 呼びなおしてください。)

戻り値の型定義 (Returned Type Definition) は、上述の API Metadata に記述されているので確認してください。(とにかく、困ったら、すぐ $metadata を見るようにしましょう !)

Action

Entity に対して、sendMail (User のメール送信)、accept (Event の承諾)、uploadContent (バイナリのアップロード) などの Action が使用できます。(使用可能な Action は API metadata に記述されています。)

例えば、下記は、Microsoft Graph を使ってメールを送信するサンプル (HTTP Request) です。

POST https://graph.microsoft.com/beta/me/sendMailContent-Type: application/jsonAuthorization: BEARER <access token>{  "Message": {"Subject": "Test mail","Body": {  "ContentType": "Text",  "Content": "Hello, Tsuyoshi !"},"ToRecipients": [  {"EmailAddress": {  "Address": "tsmatsuz@microsoft.com"}  }],"Attachments": [ ]  },  "SaveToSentItems": "false"}

上記同様、Action も、使用できる Entity Type が決まっているので注意してください。
例えば、DirectoryObject で Action “sendMail” は使用できないため、下記の呼び出しは Error になります。(下記の “manager” により User が返ってきますが、上述の通り、定義上は DirectoryObject が戻り値となっているためです。)

https://graph.microsoft.com/beta/me/manager/sendMail(This is error !)

以下は、Navigation Property “lastModifiedByUser” の戻り値の定義が User Entity であるため、権限さえあれば成功します。

https://graph.microsoft.com/beta/me/drive/items/{id of item}/lastModifiedByUser/sendMail(This succeeds !)

OData Query

もちろん、OData なので query なども可能です。(使用可能な query option は API metadata の Annotation で確認できます。なお、現 beta では、使用可能な query option もかなり制限されているようなので注意してください。) 例えば、下記は、自分の Mail Message の最初 の 3 件を取得し、その Subject のみを取得します。(通常、Body なども含む膨大なデータのため、データの転送量を抑制しています。)

https://graph.microsoft.com/beta/me/messages?$select=Subject&$top=3

下記は、自分の OneDrive のルート フォルダーの中で、name が ‘Notebooks’ のアイテム (Folder/File) を取得しています。

https://graph.microsoft.com/beta/me/drive/root/children?$filter=name+eq+'Notebooks'

また、CORS (Cross Origin Resource Sharing) もサポートしており、AngularJS など JavaScript からの呼び出しも可能です。(Release Note 参照)
Microsoft Graph をラッピングした .NET、Android、iOS、JavaScript の各ライブラリー (SDK) も提供されています。

参考情報 : Microsoft Graph
https://graph.microsoft.io/

※ 更新履歴

2015/10 : 仕様変更 (Preview API Update 2) を反映して、一部 書き換え

2015/11 : GA (General Availability) にあわせ、名称を「Office 365 Unified API」から「Microsoft Graph」に変更

2016/09 : Microsoft Graph の最新の Update を反映

2017/05 : Microsoft Graph Explorer の URL を変更