Query Office Graph using SharePoint Search API

Posted by Beau Cameron on 04.28.17
Beau Cameron
Find me on:

UPDATE: This functionality has been discontinued by Microsoft.

If you've read my blogs before you'll know that I am a firm believer in the power of search in SharePoint2013+. Search opens up many capabilities that previously we did not have access to.One of the best features that came in Office 365 was the introduction of Delve and Office Graph. If you are unfamiliar, Office Graph is a way to find content within your SharePoint environment relating to you. That is, you can use Office Graph to find recently viewed documents, documents that your coworkers are working on and even the most popular documents you may be interested in. If you've used Delve in Office365, then you are already using Office Graph without even knowing it! Delve was created as a way to improve productivity for you and your team by providing you with a dashboard of documents that may be of interest to you.

While the idea of Delve is great, sometimes it is necessary to leverage the existing technology and bring that content into your intranets to augment some functionality. You can do this by querying Office Graph through the SharePoint Search API using GQL (Graph Query Language). 

The first thing you need to know is "what can Office Graph using GQL show me?".  Office Graph gives us the ability to use relationships and interactions to find content important to us. Some of these interactions may be "documents modified" or "documents viewed" and some relationships may be "documents people around me are working on" or "documents I've worked on/viewed". Let's say you wanted to provide a way to show someone's browsing history of documents on one of your intranet pages, to try and make finding previous documents a bit easier.

If you've used the SharePoint Search REST API you'll be familar with the base syntax needed to execute a query. The syntax is as follows:

https://yoursite.sharepoint.com/_api/search/query?QueryText='*'

The API end point is _api/search/query. The parameter QueryText allows us to specify search terms. In this example I am using '*' to search EVERYTHING. However, if I wanted to find documents that contain the word "Functional Requirements", I could augment my search like so.

https://yoursite.sharepoint.com/_api/search/query?QueryText='Title:Function Requirements'

This is very important to understand if you want to limit the results that come back from the Office Graph query relating only to certain documents. Now that we have a base search query, we'll want to augment it by using Office Graph. In order to use Office Graph using the Search API, we need to add another parameter called "Properties" which is going to contain our Office Graph query. 

A basic Office Graph query contains a part called "GraphQuery" which takes parameters "actor, action" A list of actions/actors can be found here

  • Actor - Person
  • Action - modified documents,viewed documents, etc..

A standard GraphQuery would look like this:

     GraphQuery:actor(Me\,action\:1001)

If you reference the MSDN link above, you'll see that the action '1001' is the action for items viewed by the actor (myself or Me). What we want to do, is add this new Graph part to our SharePoint Search Query above. 

https://yoursite.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:actor(Me\,action\:1001)'

If you were to execute this query, you'd be searching using Office Graph to find documents that you have viewed. Great! So now we have the first part of our "Browsing History" search query. What the above query does not do, is return any of the results in the order we want. We will want to sort these documents by when I acted (viewed) on them recently by using a "Ranking Model". What a ranking model does, is allow us to specify the "weight" of the documents that are returned. In Office Graph, documents are given weights based on how much they relate to the action in the query. What we want to do is pull back the documents we have viewed most recently, with the most recent being first.

The ranking model I will use is as follows,

GraphRankingModel:{\"features\"\\:[{\"function\"\\:\"EdgeTime\"}]}'&RankingModelId='0c77ded8-c3ef-466d-929d-905670ea1d72

The most important property in this scenario is the "EdgeTime" property. This edge property is what will allow the documents to be sorted based on time. We will add this to the GraphQuery url above. Here is the end result

https://yoursite.sharepoint.com/_api/search/query?Querytext='*'&Properties='GraphQuery:ACTOR(ME\,action\:1001),GraphRankingModel:{\features\\:[{\function\\:\EdgeTime\}]}'&RankingModelId='0c77ded8-c3ef-466d-929d-905670ea1d72'

The end result is a standard search query response from the API. 

 

 OfficeGraphQuery.png

As with any other Search API Result, your results will show up in the "PrimaryQueryResult.RelevantResults.Table.Rows.results" node. From there you'll be able to grab all of the properies of your documents as you normally would using the Search API. In this result you'll notice that I've viewed 99 total documents in the Office365 environment.

 I hope you found this helpful!

Topics: Development, Search, Office Graph

Subscribe Here!

Recent Posts

Posts by Tag

See all