New Insights APIs and the discontinuation of the Office Graph GQL APIs
In addition to exposing users’ data, like who they are and what content they work with (files, messages, conversations, tasks, etc.), the Microsoft Graph also exposes calculated insights based on the users’ activity. These insights enable applications to get to relevant data about users. For example, using the Trending API to get documents that are trending or using the People API to get people they closely work with.
In March, we announced the release of our new and improved Trending API. Now, we are introducing two brand new insights to the family. The Used API and the Shared API, available from May 22, 2017.
The capabilities of the APIs in Microsoft Graph are the replacements to the GQL and SharePoint Online Search REST APIs for querying the Office Graph. See below for details.
Used API
The new Used API returns documents that users in your company have worked on and will most likely want to get back to in the future. It’s a convenient way of accessing the most relevant documents that a user viewed or modified. This includes documents used in OneDrive for Business and SharePoint.
Shared API
The Shared API provides a user with a way of getting back to the most relevant documents that others have shared with him – even a specific user. The API brings together files shared as email or meeting attachments, and modern attachments from OneDrive for Business, SharePoint and from providers like Box, DropBox and Google Drive.
Using the Insights APIs
The Insights APIs are accessible in the beta namespace in Microsoft Graph.
Used API: /insights/used
Shared API: /insights/shared
You can call the API to get documents used by you:
https://graph.microsoft.com/beta/me/insights/used
Or by someone in your organization:
https://graph.microsoft.com/beta/users/anneg@contoso.com/insights/used
To get documents shared with you:
https://graph.microsoft.com/beta/me/insights/shared
You can try calling the new API right now with our Graph explorer. Try making a call with the demo tenant or log in with your own user and see what documents you have used or have been shared with you.
Working with the results
A call to the Insights APIs returns a set of documents – the top 10 documents by default. The API supports the standard ‘top’ and ‘select’ query options.
Each returned document contains a resourceVisualization and a resourceReference complex value type (CVT).
The resourceVisualization CVT contains properties such as ‘title’ and ‘previewImageUrl’. We use visualization properties to render the files in our experiences:
The resourceReference CVT contains a ‘webUrl’ that allows you to navigate users to the location of the document.
See the Microsoft Graph documentation for more information on the Used API and Shared API.
Availability
The APIs will be available in the beta namespace in Microsoft Graph for you to start building with them on May 22, 2017.
We are currently working on making sure the results contain all the relevant data. We expect the results to be fully populated with data by July 15, 2017. Until then, there may be documents missing in the results returned by the APIs.
Discontinuing the preview Office Graph GQL APIs
Developers were able to use our preview GQL and SharePoint Online Search REST APIs for querying the Office Graph for quite some time now. The Insights APIs, together with other APIs exposed in Microsoft Graph, such as the People API, should be used instead.
The GQL APIs will be discontinued on August 31, 2017
If you’ve built apps on the preview APIs, make sure you migrate to Microsoft Graph APIs before that date. As a first step of the discontinuation, we’re introducing a query parameter called ‘EnableLegacySPOGraph’ that you need to set to ‘true’ in your calls to the SharePoint API beginning June 1, 2017.
After June 1, 2017, the API stops working without the parameter. The API then stops working completely on August 31, 2017.
Example call with without the required parameter:
Example call with the required parameter:
https://<tenant_address>/_api/search/query?querytext=’QUERY’&properties=’GraphQuery:and(ACTOR(ME,action:1020),EnableLegacySPOGraph:true’
See Querying the Office Graph to learn more about the discontinuation.
What do you think of the new Insights APIs? Let us know in the comments below!
Mario Henriques and Jakub Cech on behalf of the Insights team in Microsoft Graph.
Light
Dark