Microsoft Graph (Unified API) を使いこなそう


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 の今後のトレンドを抑えるキーワード、それは "unified" です。

例えば、OneDrive API と OneDrive for Business API など、その歴史的経緯から一般向けサービスとビジネス向けサービスの 2 つの異なる API があり機能差も生じていましたが、今後は、エンタープライズ品質を意識したビジネス版を維持しつつも、OneDrive、Outlook、OneNote などすべてサービスで、一般向けとビジネス向けの間の API の垣根 (意味のない機能差や 2 重化) は無くなっていきます。

もう 1 つは、情報にストレスなく到達する "unified" です。

Office Delve によって氾濫する情報から必要なものにストレスなく到達できようになり、今後は、活動の Insight の強化や、操作の起点としての機能も充実します。例えば、Delve 上から人に対して Skype for Business で呼び出したり、Group に対して Meet Now (今すぐミーティング) をしたり、Delve 内で Yammer の会話も可能になります。

API の世界も同様に、ここで述べる Microsoft Graph (旧 Office 365 unified api) によって、Exchange、SharePoint、OneDrive for Business など製品をまたがった参照や操作が、1 つの直観的なパス (URI) を使って可能になります。
例えば、自分のドキュメントの中で最後に更新されたファイルの更新者を確認し、その更新者の上司にメールを送信する場合、これを従来の Office 365 API で実装する場合は、OneDrive REST API、Office Graph REST API、Outlook REST API の 3 種類のエンドポイントを呼び出す必要がありますが、今後、こうした一般的な処理は Microsoft Graph を使って単一の Endpoint に対する操作で実装できるようになります。開発者にとって下記のメリットがあります。(具体的な API の使い方については後述します。)

  • リソースごとの Access Token の取り直しが不要です
  • 例えば、File Handler における「ユーザーが選択したファイルに対する Read 権限の付与」など、製品横断のさまざまなシナリオがサポートできます (利用者は OneDrive、Outlook など複数製品からファイルを選択する可能性があり、従来型の Permission ではこうした処理は不可能でした)

なお、現時点では従来型の Office 365 API (Outlook REST API, OneDrive API など) との間に多数の機能差がありますが、Excel REST API のサポート、WebHook (通知シナリオ) への対応など、Microsoft Graph の機能は拡張されていきます。(現在、これらは、Microsoft Graph の Beta 版として提供されています。) Office Delve によって Outlook, Skype などの個別の製品が無くならないのと同様、この Microsoft Graph により他の Office 365 API が無くなるわけではありませんので、必要に応じ従来型の API も使用してください。

 

すべてをまとめる API

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

Office 365 API 入門」で解説した Outlook, OneDrive などの Office 365 サービス以外に、以下の API も提供しています。

  • 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 API
    Office 365 ダッシュボードで提供している Audit 情報を API で取得できます。
  • Identity Protection
    収集されたリスク イベントの情報を API で取得できます。
  • Intune
    Intune が新しい Azure Portal (コードネーム Ibiza) に統合されるのとあわせて、Microsoft Graph 上からデバイス構成やアプリケーションの管理をおこなえるようになります。Intune の管理作業の自動化で使用できます。

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/sendMail
Content-Type: application/json
Authorization: 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 をラッピングした .NETAndroidiOS、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 を変更

 

Comments (0)

Skip to main content