Exploring Office 365 with the Graph Explorer
In the Beginning: PowerShell, EWS, and PnP
When Microsoft launched Office 365 in June 2011, the basic workloads brought their own approaches to automation to Office 365. After many mishaps with APIs that never quite worked as intended, much of the focus for Exchange was on PowerShell. This was natural because Exchange 2007 was the first major Microsoft server product to embrace PowerShell.
However good PowerShell is at automating common administrative tasks, it does not handle access to content. To close this gap, Exchange Web Services (EWS) handles programmatic access to data in user mailboxes. EWS is the basis of the Outlook for Mac client and is a very effective method to access Exchange data, as you can find out by examining the many code examples available on the Internet, including the repository managed by MVP Glen Scales.
SharePoint also supports PowerShell, but the coverage of the SharePoint PowerShell module is less comprehensive and powerful than its Exchange counterpart. For this reason, the SharePoint development community built the SharePoint PnP (Patterns and Practice) initiative. PnP is an excellent choice for developers who want to extend SharePoint functionality.
The Microsoft Graph
Office 365 is a different environment. PowerShell plays a key role in the automation of Office 365 administrative. EWS is available to access mailbox data and PnP continues to flourish. However, for programmatic access, Microsoft’s focus is clearly on a set of REST-based APIs for a common access approach to all manner of Office 365 data from Exchange and SharePoint to Teams and Planner.
Collectively, the APIs are the Microsoft Graph, a single API to interact with Office 365 data via multiple endpoints. An endpoint is something like mail, contacts, calendar, or groups. All the calls are via standard HTTP requests, which means that programmers can use a wide variety of programming languages. For example, GET requests fetch data while POST requests write data.
The Microsoft Graph is now a critical part of Office 365. It is used by Microsoft developers to create new applications like Teams and MyAnalytics and the mobile apps for many workloads within Office 365. The Microsoft Graph also includes data from outside Office 365, such as Azure Active Directory and Microsoft’s consumer cloud services, meaning that it is possible for programmers to mix and match data drawn from multiple sources within the same application. It is even possible to use the Graph API to access mail, calendar, and contacts data on Exchange 2016 on-premises servers, providing certain requirements are met.
Microsoft has deliberately made the Graph approachable by including support for a wide choice of development technologies (Figure 1). By using the Graph APIs, programmers can do the following:
- Access data from multiple applications, such as Exchange Online and SharePoint Online.
- Traverse data accessed by users to be able to track their usage of the service.
- Understand data trends to be able to find data that is important to the tenant or groups of users.
Microsoft hopes that programmers will use the Microsoft Graph to build new forms of applications that take a more holistic view of the data available to a user rather than the traditional stovepipe view bounded by a single application
For example, although Exchange Online spans messaging, calendar, and tasks, a limited view of user activity is available to EWS because Exchange does not know about the documents people are working on or sharing with others inside the company, Skype calls that they make or conference calls they attend, or have any idea about the videos that they might be viewing or the plans they make.
The Microsoft Graph Explorer
Full documentation about the various endpoints available to Office 365 data through the Microsoft Graph is available online. You will notice that some of the endpoints are marked with a version number (such as V1.0) and some are still marked as “[email protected], showing that these endpoints are still under development. Of course, there is nothing like using something to get to know what it is capable of. To understand the capabilities of the Microsoft Graph, you can fire up the Graph Explorer, a web console that allows you to execute different API calls against real data.
As I learned in an interesting session delivered by Andrew Connell at the recent Office 365 Engage conference, the idea behind the Graph Explorer is that it helps programmers understand the kind of calls they need to construct to interact with various Office 365 endpoints and the format of the results returned through their interaction.
You can select “V1.0” or “beta” from the drop-down list to move between the sets of supported calls. The field holding the selected call offers an IntelliSense-like auto-complete capability, so you can click it to reveal the calls available from a specific point. For instance, assume that we select https://graph.microsoft.com/beta/me/ as a starting point. If you now click the field, you see a list of calls organized (somewhat alphabetically) starting with https://graph.microsoft.com/beta/me/businessPhones and then https://graph.microsoft.com/beta/me/city and so on.
Exploring Your Data
Although you can use the Graph Explorer to examine data in a test tenant, the experience is more forceful when you authenticate your account. When this happens, the Graph returns the information that the authenticated user would see. After you enter a specific query or select one of the “Getting Started” examples, click Run Query to have Office 365 return the requested data. For instance, Figure 2 shows the results of a call to fetch data from https://graph.microsoft.com/v1.0/me/drive/root/children, which returns the set of documents in my OneDrive for Business site. Whenever you see “Me” used in a Graph call, you know it is a pseudonym for the logged-on account.
A single authentication is enough to access all user endpoints (a personal mailbox), but you need to change permissions to gain administrative access to others, such as the set of Office 365 Groups known in the tenant. You know when you need access rights to access an endpoint because you will see the standard 401-access denied response when you try to access data. The solution is to edit the permissions used with the Graph Explorer and then log-on again to create a new session with the extended permission set.
Apart from the obvious calls to play with, such as https://graph.microsoft.com/v1.0/me/messages (list all messages in your Inbox), other interesting endpoints to investigate are:
- https://graph.microsoft.com/beta/groups: List all the groups in a tenant.
- https://graph.microsoft.com/beta/me/joinedGroups: List all the Office 365 Groups that the logged-on user belongs to in a tenant (See this blog for more information about using the Microsoft Graph with Office 365 Groups).
- https://graph.microsoft.com/beta/me/joinedTeams: List all the Teams that the logged-on user belongs to in a tenant.
When you list sets of objects like Groups or Teams, you see an identifier for each object. You need the identifier (a GUID) to navigate to the next level. For instance, this URL includes a group identifier https://graph.microsoft.com/beta/groups/72ee570e-3dd8-41d2-bc84-7c9eb8024dd4. Including that URL in a query returns the properties of the group in JSON format. For example:
"classification": "External Access",
"description": "Exchange Grumpy Old Men (and Women too)",
"displayName": "Exchange's Grumpy Old Men",
"mail": "[email protected]",
Different to PowerShell
If you know the PowerShell cmdlets for Office 365 Groups, you can see that the set of properties returned for a group is different from the set returned by the PowerShell Get-UnifiedGroup cmdlet. This does not mean that the Microsoft Graph is not as good as the PowerShell cmdlets. Instead, the capabilities available through PowerShell and the Microsoft Graph are very different. Where PowerShell deals with administrative tasks, the Microsoft Graph handles some administration but manipulating content is more important.
In the case of Groups, you can use the Microsoft Graph to read and write conversations, files, and the shared calendar, none of which PowerShell can access. And in some cases, like Planner and Teams, applications have no PowerShell support apart from that available for Groups, and the Microsoft Graph is the only way to interact with their content.
The Graph is the Future
At this point in my career, I am no programmer. Writing code is now the trade of those who understand the subtleties of web applications and not a place for washed-up COBOL guys to go. Yet I like what I see in the Microsoft Graph and how it brings all of Office 365 together for programmers. And the Graph Explorer is just an excellent tool to help people embrace the Graph. All of which is good for those of us who try to keep up-to-date with what happens inside Office 365.
Follow Tony on Twitter @12Knocksinna.
Want to know more about how to manage Office 365? Find what you need to know in “Office 365 for IT Pros”, the most comprehensive eBook covering all aspects of Office 365. Available in PDF and EPUB formats (suitable for iBooks) or for Amazon Kindle.