2017/05 : 本投稿で解説する Office Graph GQL (Preview) は、提供終了となりました。詳細は「New Insights APIs and the discontinuation of the Office Graph GQL APIs」を参照してください。

こんにちは。

この投稿では、Office Graph を使った開発について紹介します。

Office Graph って何 (短く解説)

Office Graph は、ビジネスでやりとりされる E-Mail、Yammer、OneDrive for Business のドキュメントなど Office 365 のシグナル (利用者の過去の行動) に基づき、機械学習技術 (machine learning) やグラフ技術を使って、その関係性 (グラフ) を管理します。(将来的には OneNote、Lync など、その他のシグナルも対象となる予定とのことです。)

例えば、Office 365 の先行リリースとして追加された Office Delve (旧コードネーム Oslo) は、Office Graph の技術を利用した具体的なアプリケーションの 1 つで、Personalize された Recommendation (必要そうな情報) をボード形式で出力します。(Office 365 の Launcher から「Delve」を選択して使用できます。モバイル ビューにも対応しています。)
また、Office 365 の Outlook では、Office Graph を使って重要なメールに迅速に到達できる Clutter という機能も提供しています。

(上図は Delve の画面イメージです。私の仕事の情報がバレるので一部隠ぺいしてます。。。)

こうした現在公開されている機能に限らず、今後も Office Graph を使ったさまざまな拡張 (必要な情報への迅速な到達) が期待できます。

Office Graph を使った開発 – API の利用

Facebook アプリでは、例えば、自分の友達の間で話題のトピックを表示したり、近い友達のアクティビティがレポートされるようなアプリを見かけることがあると思いますが、Office Graph を使うとビジネスの世界でもこうした提案型 (Recommendation) のアプリケーションを構築できます。

もちろん、まず API を使用する前に、Office Graph が使用できるようにセットアップしておきましょう。

• 2015 年 01 月現在では、Office 365 の E プランで、下図の通り 先行リリース (First Release) の更新 (Update) を有効にしてください。(有効でない場合、後述する API で “Graph queries currently disabled” のエラーが出ます。)
  有効になると Office Delve が使えるようになります。(使用開始までは時間がかかります。1 日くらい余裕を見ておきましょう。)
  
• これから動作を試したいという方は、Office 365 の Exchange 管理センター (Exchange Administration Center) で、各ユーザーの上司 (Manager) を設定してください。(既に会社で使用されている方などは、たぶん既に設定済かと思います。)
  なお、この設定が Office Graph に検知されるまでには少し時間がかかります。(約 1 時間ほどかかります。)

Office Graph の API も Office 365 API に対応しています。このため、基本的な開発 (プログラミング) の流れは、OAuth でトークンを取得し、REST を使って Office Graph API を呼び出すという これまでの流れと同じです。(OAuth も含めたフローについては、上記リンクを参照してください。)

補足 : なお、access token を取得する際、resource name は、SharePoint と同じ値 (https://<your tenant>.sharepoint.com) を指定してください。
また、Permission 設定では、[Run file search queries as a user] を設定しておいてください。

REST を使った Office Graph API については、以下にドキュメントが公開されているので参考にしてください。

Query the Office Graph using GQL and SharePoint Online Search REST APIs
https://msdn.microsoft.com/en-us/office/office365/howto/query-Office-graph-using-gql-with-search-rest-api

要約すると、Office Graph API (REST のフォーマット) では、Actor と Action を指定する GQL (Graph Query Language) を発行し、返される Object (人やアイテム) を取得します。(AND、OR も可能です。)

2015 年 01 月現在、この GQL で出来ることは以下です。

例えば、皆さんが最近よく編集しているドキュメントを検索する場合は、上記の Modified (1003) を使用して以下の通り要求します。

GET https://<your tenant name>.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(ME%5C,%20action%5C:1003)'Accept: application/jsonAuthorization: Bearer <access token>

結果 (Response) は以下の通りです。(一部結果を省略しています。)
頻繁に変更しているドキュメントなど、優先度は Rank で指定されます。また、Property 情報が大量に出てくるので、実際の開発では、上記の Properties パラメーターで必要なものだけに絞ってください。

{  "odata.metadata": "https://.sharepoint.com/_api/$metadata#Microsoft.Office.Server.Search.REST.SearchResult",  "ElapsedTime": 137,  "PrimaryQueryResult": {"CustomResults": [],"QueryId": "93b8a113-24e2-4d6e-b282-e2f0fb705f95","QueryRuleId": "00000000-0000-0000-0000-000000000000","RefinementResults": null,"RelevantResults": {  "GroupTemplateId": null,  "ItemTemplateId": null,  "Properties": [{  "Key": "GenerationId",  "Value": "9223372036854775806",  "ValueType": "Edm.Int64"},{  "Key": "indexSystem",  "Value": "",  "ValueType": "Edm.String"},. . .  ],  "ResultTitle": null,  "ResultTitleUrl": null,  "RowCount": 10,  "Table": {"Rows": [  {"Cells": [  {"Key": "Rank","Value": "5.76791286468506","ValueType": "Edm.Double"  },  {"Key": "DocId","Value": "151713816","ValueType": "Edm.Int64"  },  {"Key": "Title","Value": "Book01","ValueType": "Edm.String"  },  {"Key": "Path","Value": . . . ,"ValueType": "Edm.String"  },  . . .]  },  {"Cells": [  {"Key": "Rank","Value": "5.69491100311279","ValueType": "Edm.Double"  },  {"Key": "DocId","Value": "151718234","ValueType": "Edm.Int64"  },  {"Key": "Title","Value": "Book-tsmatsuz01","ValueType": "Edm.String"  },  {"Key": "Path","Value": . . . ,"ValueType": "Edm.String"  },  . . .]  },  . . .]  },  "TotalRows": 10,  "TotalRowsIncludingDuplicates": 2},"SpecialTermResults": null  },  "Properties": [{  "Key": "RowLimit",  "Value": "10",  "ValueType": "Edm.Int32"},{  "Key": "SourceId",  "Value": "02329dfc-758e-4532-9c60-492fa63d4c45",  "ValueType": "Edm.Guid"},. . .  ],  "SecondaryQueryResults": [  ],  "SpellingSuggestion": null,  "TriggeredRules": [  ]}

会社 (ビジネス) で仲良くやりとりしている人を検索する場合は、WorkingWith (1019) を使用して以下の通り検索できます。(以降、Response は省略します。)
なお、この場合、private でやりとりしている人も表示されます。

GET https://<your tenant name>.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(ME%5C,%20action%5C:1019)'Accept: application/jsonAuthorization: Bearer <access token>

さらに、人のネットワークをたどっていく場合は以下の通りになります。今回は、WorkingWithPublic (1033) を使って、Public な関係のみを取得します。
また、下記の「32492198」は上記の検索結果のうちの 1 名の ActorId と仮定します。(検索結果の ObjectId から取得できます。)

GET https://<your tenant domain>.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(32492198%5C,%20action%5C:1033)'Accept: application/jsonAuthorization: Bearer <access token>

「自分が編集 (作成含む) したもので、まわりで人気のアイテム」を検索する場合は、以下のように AND を使います。

GET https://<your tenant name>.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:AND(ACTOR(ME%5C,%20action%5C:1003)%5C,%20ACTOR(ME%5C,%20action%5C:1020))'Accept: application/jsonAuthorization: Bearer <access token>

Office 365 を実際に会社で使用されている方は (ただし、Delve が有効である必要があります)、検索結果の精度などを是非試してみてください。(Microsoft 社員の方は User Consent が許可されていないので使用できません。)