Connect(); 2016

Volume 31 Number 12

[Office]

Microsoft Graph: Gateway to Data and Intelligence

By Yina Arenas; 2016

A key strategy for Microsoft is to “reinvent productivity” by empowering developers to build smart, people-centric applications on the Microsoft platform so users can get more out of work and life.

The way we work is rapidly evolving. People seem to always be connected and users expect applications to help them with the task at hand—in the precise moment where they’re needed, right where they are, and with the relevant context that can intelligently leverage the data available to make meaningful connections between people and information, and make productive use of the most valuable commodity: time.

Imagine an app that can look at your next meeting and help you prepare for it, such as providing useful profile information for attendees that includes not only their job titles, but also who they work with and information on the latest documents or projects on which they’re working.

Or, imagine an app that not only has access to your calendar, but suggests the best times for the next team meeting.

How about an app that can get the latest sales projection chart from an Excel file sitting in your OneDrive and lets you update the forecast in real time, all from your mobile phone?

Or, how about an app that can subscribe to changes to your calendar, alert you when you’re spending too much time in meetings, and provide recommendations for the ones you could miss or delegate based on how relevant the attendees are to you?

Or, how about an app that can help you sort out personal and work information on your phone, like pictures that should go to your OneDrive because they’re your children’s pictures versus pictures that should go to your OneDrive for business because they’re pictures of receipts for an expense report.

All of these app examples can easily be powered by Microsoft Graph.

Unparalleled Opportunities for Developers

In an age of information abundance, we know that people are seeking integrated experiences to help them leverage many sources of data and connect information from multiple touchpoints in meaningful ways. Here’s where Microsoft Graph is the key enabler, empowering developers to create powerful and personalized cloud-based apps that can transform the productivity landscape.

If you look at the massive amount of data available for developers, you’ll see that there are about 850 million Outlook meetings scheduled per month and more than 100 million of those are Skype meetings. There have been 4 trillion e-mails sent to date using Office and hundreds of petabytes of data stored in Office 365. Users spend an average of two to three hours each day in Office and, now that Office apps are mobile, the mobile Office apps just surpassed 340 million downloads; this reach wasn’t possible just two years ago!

Microsoft Graph: Easing Integration

Microsoft Graph (graph.microsoft.com) was created to meet user demand for smart contextual experiences and to ease the developer pain of integrating with Microsoft services one at a time to create them. Microsoft Graph is the unified gateway for developers to access all the data, intelligence and APIs housed in Microsoft’s intelligent cloud including Exchange, SharePoint, Azure Active Directory, OneDrive, Outlook, OneNote, Planner, Excel and more. Microsoft Graph also includes calculated insights and rich relationships based on machine learning performed by its intelligent engine. All this is available through the same REST API endpoint, providing a much simpler developer experience across all of Microsoft’s APIs by bringing them together in a single URI namespace with a single authentication story.

The reason why Microsoft Graph is so important is because the data that’s in Office 365—the organizational hierarchy, the calendar, the mailbox, the files and so on—are cornerstones for organizations and how people get things done. And the easier your applications can leverage all that data, the smarter they can be and the better experiences they can provide for users.

As shown in Figure 1, Microsoft Graph aggregates information from multiple services and makes it available to the application in a single request. Developers can build user- and group-centered experiences that help users achieve more. An example: a productivity app that gives you the profile and picture of all the people you’re about to meet and can tell you their organizational structure and the topics relevant to them. It doesn’t matter where the data is stored; with Microsoft Graph you get a single endpoint to access it.

Figure 1 Microsoft Graph Lets Apps Access Digital Work and Digital Life Data

Microsoft Graph can also be used to traverse data across services to empower rich content scenarios. An example: an educational app that models classrooms around groups and lets the teacher track the documents students submit for their projects, see who modified the files, track their collaboration and progress, and have conversations around topics relevant to the class.

Access to Intelligence

Microsoft Graph surfaces intelligent insights by bringing together smart machine learning algorithms with a wealth of data and user behavior. Using Microsoft Graph, developers can access this relevant data to make applications contextual and smarter. For example: people picking controls powered by the People API in Microsoft Graph, where leveraging its fuzzy matching functionality, users don’t have to remember how to spell some complicated last name and can get to the data just by remembering how it phonetically sounds. Imagine a sales app where the sales representative can quickly get to his customer’s contact information and have it on the spot when needed. How many times have you forgotten how to spell a name and then have to scramble to find the contact based on other keywords?

Another example of Microsoft Graph intelligence is its ability to get trending documents. Microsoft Graph listens to signals and activities such as file uploads, file views and modifications, e-mail conversations, and so on. Then it uses its intelligent engine to calculate rich relationships and inferred insights between people and documents. When a file becomes popular in your circle, Microsoft Graph creates a trending insight; this information then becomes available to power contextual experiences such as Delve in Office 365 and now is also available to developers as an API in Microsoft Graph.

Reach Millions of Users

Microsoft Graph is also the unified endpoint for consumer and commercial clouds. The lines between work and personal productivity are increasingly blurring. That app that can sort your personal and work photos to OneDrive and OneDrive for Business can be written with a single code base and a single app registration using Microsoft Graph. This means that developers can use this single endpoint and the same code to access personal data sitting in Outlook.com, Hotmail.com, Live.com, and other personal accounts in the Microsoft cloud, as well as with work and school data sitting in Office 365 and Azure Active Directory accounts. So, with Microsoft Graph, you use the same code with a single app registration and a single auth flow.

In addition to being the unified endpoint for consumer and commercial services, Microsoft Graph is also the unified endpoint for sovereign deployments. Microsoft announced the general availability of Microsoft Graph in China this year. That has strengthened the ISV ecosystem in China and empowered multi-national ISVs to build smarter apps for the Chinese market. As more sovereign clouds become available in other markets, Microsoft Graph becomes the gateway to access their data.

Furthermore, Microsoft Graph wants to close the programmability gap between the cloud and on-premises. Now in preview, Microsoft Graph can reach out to Exchange 2016 mailboxes sitting on-premises for customers with hybrid deployments. From the development perspective, the code can be agnostic to where the data is coming from and the same code can get data from a mailbox in the cloud (whether it’s an Office 365 mailbox or an Outlook.com/Hotmail.com mailbox) or a mailbox on-premises. Microsoft Graph takes care or finding where the data lives and retrieving it for the app.

Microsoft Graph Is Core to the Office Platform

Microsoft Graph alters the landscape of work and productivity for IT, users and developers. For IT, apps are easier to deploy and manage due to their graph integration and because data access is secured. For users, apps are smarter, richer and contextual. For developers, Microsoft Graph brings tremendous value by shortening development time and making it simple to integrate with data and intelligence.

Today, innovative businesses are transforming work and productivity through Microsoft Graph. For example:

• Zapier: Uses the Microsoft Graph to tap into Excel data and let users create powerful “zaps” or personal workflows that automate data collection into Excel and integrate it with other cloud services. This is an integration that wasn’t possible before Microsoft Graph and its Excel REST API.
• Smartsheet: Integrates with Microsoft Graph in Outlook to give the Outlook user the ability to interact with the sheets and projects in Smartsheet right from the Outlook experience while leveraging data from OneDrive and other services.
• SkyHigh Networks: Leverages Microsoft Graph to enable security teams to gain visibility into sensitive data, apply data loss prevention policy to users or groups, and identify or alert high-risk behavior.
• Hyperfish: A brand-new startup that enables organizations to automatically identify and populate missing user profile information quickly and easily. It turns blank people cards into rich cards that enable faster people connections.
• Workday: Uses Microsoft Graph to integrate with Office 365 groups such that when an employee starts a new position in the organization, all changes in Workday are automatically reflected in Office 365 groups and the employee gets imme­diate access to all events, conversations and documents.

The API

Microsoft Graph uses Web standards that enable any device capable of making an HTTP request to interact with it. It’s a RESTful API that follows Microsoft REST API guidelines recently made public to the API community and available at bit.ly/2dzFp1a. Many portions of the Microsoft REST API guidelines evolved from standardization and rationalization exercises to unify the existing service APIs and their direct endpoints and schemas, so that they could participate in Microsoft Graph. I personally wrote the first proposal for naming conventions and casing that went into the guidelines and was part of long, internal API debates among more than 15 teams across Microsoft that collaborated in the creation of Microsoft Graph.

Microsoft Graph supports a rich set of query parameters such as select, filter, expand, and orderBy that can be used to specify and control the amount of data returned in the response. Microsoft Graph also has a growing set of SDKs for devices and services—so whether you’re working on iOS, Android, or Universal Windows Platform (UWP) apps, creating a .NET Azure Web site, or building a service with Node.js, Python, PHP, or Ruby, you can quickly incorporate Microsoft Graph data into your application.

Getting Started with Microsoft Graph

So how can you leverage Microsoft Graph? Start by navigating to graph.microsoft.io. This will take you to the developer portal, where you’ll find quick-start experiences that can bootstrap your development and, in less than five minutes, you’ll have a working application in the platform of your choice calling Microsoft Graph.

At the Microsoft Graph developer portal, you’ll also find documentation, complete API reference, a full suite of SDKs and code samples on a variety of platforms, and the Graph explorer. Using the Graph explorer, you’ll be able to send requests to Microsoft Graph and inspect the response right away using your personal account, your work or school account, or even a demo account. Figure 2 shows some sample requests showcasing the type of data that can be accessed using Microsoft Graph. Data can be read, created, updated and deleted using the APIs. You can easily try all of these requests and more using the Graph explorer.

Figure 2 Sample Requests in Microsoft Graph

Now I’ll take a look at Microsoft Graph in more detail. You start by using the Getting Started link at graph.microsoft.io to create an ASP.NET MVC Web application that uses the Microsoft Graph .NET SDK to send mail on the user’s behalf. Then you enhance it with an additional call to the OneDrive API exposed in Microsoft Graph to query for the user’s recent files.

After navigating to the Get started page and interacting with the try experience, navigate toward the bottom of the page and select the ASP.NET MVC entry point.

The next step is to follow the links to register the app. Remember to copy the “secret” and save it as it won’t be presented to you again. After this process, you’ll get a .zip package with the project. Extract the files, open the project in Visual Studio, build it and run it. If you need to make updates or changes to the registered app you can make them at apps.dev.microsoft.com.

This quick-start experience grabs the code sample, inserts the application id and the secret in the web.config file and leaves the project ready for you to run. The running app is the resulting ASP.NET 4.6 MVC Web app that connects to a Microsoft work or school (Azure Active Directory) or personal (Microsoft) account using the Microsoft Graph API to send an e-mail. It uses the Microsoft Graph .NET SDK to work with data returned by Microsoft Graph.

Now that you have the project up and running, you’ll add the calls to the OneDrive API to get the list of items that have been recently used by the signed-in user. This list includes items that are in the user’s drives, as well as items she has access to from other drives.

The first step is to modify the web.config file to add the Files.Read permission scope to let the application read access to the user’s OneDrive. In the web.config file, look for the ida:GraphScopes key in the appSettings element and add Files.Read to the value string. The next time the user launches the app, the service will identify the new scope and dynamically ask the user to consent for it:

<appSettings>
  ...
  <add key="ida.GraphScopes" value="User.Read Mail.Send Files.Read" />
</appSettings>

Next, you’ll modify the controller. Open HomeController.cs in the Controllers folder; this class contains the actions that initialize the Microsoft Graph .NET SDK in response to the UI events. Add the method in Figure 3 to get the top 10 recent OneDrive items.

Figure 3 Acquiring Top 10 Recent OneDrive Items

[Authorize]
// Get the items that are shared with the current user.
public async Task<ActionResult> GetMyRecentItems()
{
  try
    {
      // Initialize the GraphServiceClient.
        GraphServiceClient graphClient = SDKHelper.GetAuthenticatedClient();
        // Get the recent items.
        ViewBag.RecentItems =
          await graphClient.Me.Drive.Recent().Request().Top(10).GetAsync();
        return View("Graph");
      }
      catch (ServiceException se)
      {
        if (se.Error.Message ==
          Resource.Error_AuthChallengeNeeded) return new EmptyResult();
        return RedirectToAction("Index", "Error", new { message =
          string.Format(Resource.Error_Message, Request.RawUrl,
          se.Error.Code, se.Error.Message) });
      }           
}

Notice the [Authorize] statement before the method. This is there to ensure this request will initiate a sign-in if the user isn’t already signed in.

Finally, update the view Graph.cshtml in the Views folder to include a button that will trigger the request and divs to render the name of the item and the name of the user who created the item for each of the items in the returned list. Do this by appending the code in Figure 4 at the end of the file.

Figure 4 Update the View Graph.cshtml in the Views Folder

<h2>Recent OneDrive Items</h2>
@using (Html.BeginForm("GetMyRecentItems", "Home"))
{
  <div class="col-sm-12">
    <div class="form-group">
      <button class="btn btn-default">Get Recent OneDrive Items</button>
    </div>
  </div>
}
<div class="col-sm-12">
  <label for="recent-items">Recent Items</label>
  @if (ViewBag.RecentItems != null)
  {
    foreach (var item in ViewBag.RecentItems)
    {
      <div class="row">
        <div class="col-sm-4">@item.Name</div>
        <div class="col-sm-8">@item.CreatedBy.User.DisplayName</div>
      </div>
    }
  }
</div>

The result is an ASP.NET 4.6 MVC Web app that connects to Microsoft Graph and can be used by users with Microsoft work or school (Azure Active Directory) accounts or users with personal (Microsoft) accounts to send an e-mail from their Outlook.com or Office 365 mailbox and access OneDrive or OneDrive for Business data. This is a simple example that illustrates how easy it is to get data from the Microsoft cloud using Microsoft Graph, whether that data comes from Azure Active Directory, SharePoint, OneDrive, Exchange, Outlook.com, Planner, OneNote, Excel, or other services.

Imagine the applications that you can build. Microsoft is working to increase the number of services and functionality available in Microsoft Graph, on deepening its understanding of user activity to make richer inferences and relationships, and simplifying the developer experience so you can access all of this data from a single connected API.

This is a massive opportunity for developers, who can tap into all this data and intelligence using the Microsoft Graph. The momentum behind Microsoft Graph since it launched in Novem­ber 2015 speaks to this. Microsoft has seen a huge uptake in the number of registered apps, the organizations that consent to apps that use Microsoft Graph, and end-user active usage of those apps. Some of these apps built using Microsoft Graph are already reaching millions of active daily users.

Wrapping Up

With Microsoft Graph, developers are empowered to build smart, people-centric apps that can easily interact with data from all touch points of modern work. It enables developers to take advantage of the tremendous amount of data in Microsoft’s cloud services—to build smarter apps and help people be more productive. Microsoft Graph exposes APIs, data, and intelligence across Office 365 and Azure Active Directory. Microsoft is building toward a near future where multiple graphs and all APIs throughout Microsoft contribute to, and are accessible through, a single unified gateway to the power of the Microsoft cloud. This translates into the ecosystem helping reinvent productivity by creating sticky experiences in all industry verticals. It opens a future where developers can re-shape health care, education, finance, law and many more industries; the possibilities are endless. I can’t wait to see what you build using Microsoft Graph.

Yina Arenas is a principal program manager at Microsoft and lead for Microsoft Graph. She’s taking Office and Microsoft APIs from legacy and disjointed technologies to a new, unified API world. She lives in the Seattle area with her husband and their three energetic boys and actively leads and participates in activities that grow, retain, and empower women in technology. Find her on Twitter: @yina_arenas.

Thanks to the following Microsoft technical experts for reviewing this article: Agnieszka Girling, Gareth Jones and Dan Kershaw
Agnieszka Girling, Gareth Jones, and Dan Kershaw are principal program managers on the Microsoft Graph team that, along with Yina Arenas, are helping design the API and are responsible for the all-up design choices and technical direction of Microsoft's most strategic API.

Discuss this article in the MSDN Magazine forum