GET-ting Your Office 365 Data Using the Microsoft Graph API

Published 11/02/2018 03:55 PM   |    Updated 11/13/2018 02:54 PM
This article originally appeared on May 4, 2017.
 
In almost every project these days, the cloud is part of a client's needs or wants — whether this is around helping to migrate data (Exchange, OneDrive, Planner and/or SharePoint) or leveraging existing usage of Office 365 better. One of the common asks that comes up is how to help employees access their digital work and digital life data across all of Office 365 in one place.
 
Enabling inline social experiences, such as surfacing the rich data of a user's mail/calendar and documents in one interface, can increase user adoption, as well as help with critical work and productivity questions. Such smart, people-centric applications can be designed to easily interact with data from all touchpoints of a user’s workloads. To support these types of applications, we can use the Microsoft Graph API to pull through the users’ data in a single interface.
 

What is the Microsoft Graph API?

 
Microsoft Graph, previously known as the Office 365 unified API, exposes the multiple APIs from Office 365 services through one REST API endpoint. We can easily query the secured API to access fixed entities such as users, groups, mail, messages, calendars, tasks and notes that come from Outlook, OneDrive, Azure Active Directory, Planner, OneNote and several others. All of these entities only need a single authentication token and a well-formed URL to return their results.
 
Microsoft Graph API
 

How do I access it?


As developers, we can start immediately building Microsoft Graph-based solutions for free using an Office 365 developer tenant, with access to the Office 365 APIs included in the Office 365 license. This includes all of the APIs that are available with the general release. The query response is returned to us as JSON, which meets normal web development standards for data.
 
The easiest starting point is to use the browser-based Graph Explorer, located on the Microsoft Graph site. After logging in with developer credentials to create the authentication token, we can launch GET commands to pull data about that account from Office 365. The left column has preset queries that show us which API endpoints are available for quick use.
 
Microsoft Graph API
 
The tool also keeps a history of our queries so we can easily go back and forth to previous calls.
 
Microsoft Graph API
 
After signing into Microsoft on the site and obtaining our authorization token, the API to use is broken out into three major components that are attached to the Microsoft Graph API endpoint:
 
https://graph.microsoft.com/{version}/{resource}?[odata_query_parameters]
 
  • {version} is the target service version, with v1.0 as the current Production Release or beta.
  • {resource} is resource segment or path, such as users, groups, devices, organization.
    • The alias “me,” which resolves to the signed-in user
    • The resources belonging to a user, such as me/events, me/drive or me/messages
    • The alias myOrganization, which resolves to the tenant of the organization signed-in user
  • [odata_query_parameters] represents additional OData query parameters such as $filter, $top, or $select.
As an example, here are some common queries using the Microsoft Graph API: 
 
GET my profile - https://graph.microsoft.com/v1.0/me
 
Microsoft Graph API - GET my profile
 
GET my files - https://graph.microsoft.com/v1.0/me/drive/root/children
 
Microsoft Graph API - GET my files
 
GET my photo - https://graph.microsoft.com/v1.0/me/photo
 
Microsoft Graph API - GET my photo
 
Microsoft Graph API - GET my photo 2
 
GET my mail - https://graph.microsoft.com/v1.0/me/messages
 
Microsoft Graph API - GET my mail
 
GET my next 5 upcoming Events -
https://graph.microsoft.com/v1.0/me/events?$top=5&$select=subject,body,bodyPreview,organizer,start,end,location&$filter=Start/DateTime+ge+'2017-04-17T00:00:00Z'
 
Microsoft Graph API - GET my upcoming events
 
Get other Users - https://graph.microsoft.com/v1.0/users
 
Microsoft Graph API - GET other users
 

What should I do with it?


When getting ready to build an application to use the Microsoft Graph API, an application must enable users to authenticate their identity and give consent for the application to query on their behalf. There are two authentication providers Microsoft Graph supports currently: For live.com or outlook.com accounts, the Azure AD v2.0 endpoint is supported; for enterprise users, only the Azure AD endpoint is allowed.
After deciding which authentication provider meets your application's requirements, you need to register the app at that authentication provider's portal. Registering the app establishes its identity with the authentication provider and enables the app to specify its identity when submitting authentication requests from the user. After registering the app with the appropriate authentication portal and getting the registration information (app ID, app secret, if applicable, and redirect URL) needed to establish the app's identity, we can begin building it out using our code base of choice, such as JavaScript, ASP.NET, Android or many others.
No matter the medium, using the Microsoft Graph API gives us the capability to surface a user's mail, calendar or OneDrive content in a form factor that meets their working needs. This can be as simple as a small web part that lives on an intranet homepage showing the user’s latest office content or up to custom mobile applications. Surfacing this content for the user in interfaces he or she is already working within allows them to work smarter and get more done while feeling more connected to their organization.
 

Is this answer helpful?