Building Solutions with Microsoft Graph Purvin Desai Cloud and SharePoint Architect Follow @purvd Building solutions with Microsoft Graph TABLE OF CONTENTS Introduction ........................................................................................................................................................ 1 What is Microsoft Graph? ................................................................................................................................... 1 service Architecture ............................................................................................................................................ 1 Microsoft Graph API metadata ........................................................................................................................... 4 TraveRsing the graph .......................................................................................................................................... 4 Graph Explorer .................................................................................................................................................... 5 Microsoft Graph SDKs ......................................................................................................................................... 5 Paging Capabilities .............................................................................................................................................. 5 Service Exceptions & Throttling .......................................................................................................................... 5 CRUD Capabilities ............................................................................................................................................... 6 Notifications ....................................................................................................................................................... 6 Type Extensions .................................................................................................................................................. 6 Summary ............................................................................................................................................................. 7 Explore ................................................................................................................................................................ 7 Building solutions with Microsoft Graph INTRODUCTION Note: Microsoft Graph has two endpoints: V1.0 and beta. Some of the content in the document refer to beta endpoint, and it is not recommended to build production code with beta endpoints. WHAT IS MICROSOFT GRAPH? Microsoft Graph (previously called Office 365 unified API) is a unified API endpoint, based on advanced machine learning algorithms which are fed by data and user behavior and intelligently makes connections between siloed entities. This unified API (https://graph.microsoft.com) aggregates data from multiple Microsoft cloud services like Outlook, OneDrive, Azure Active Directory, OneNote, Office Graph, etc. This API has full CRUD capabilities and in addition provides mechanisms for subscribing to notifications. It also allows extending existing entities with certain types. Microsoft Graph provides deep insights, analytics and relationships between various entities. Prior to Microsoft Graph, in order to work with these services, you would have to make calls to different endpoints of the respective services. It required complex authentication flows in order to communicate with multiple services from with a single application. With unified API, one can work with multiple services with a single authentication token. Microsoft Graph is a complete solution that takes advantage of wealth of information available in an enterprise or in public cloud. This document documents various aspects of Microsoft Graph and how it they can used to build amazing experiences that will delight users and help us to be more productive. SERVICE ARCHITECTURE Fig. Service Arcitecture (ref: https://graph.microsoft.io) 1 Building solutions with Microsoft Graph OFFICE GRAPH Office 365 is Microsoft’s cloud platform for the enterprise and the consumers. It’s a suite of services ranging from Email, Exchange Online, document storage in OneDrive for Business and content management in SharePoint. It even includes Word, Excel and PowerPoint running on client machines or in your browser. Inside Office 365, there is a wealth of data and relationships, that we store in what we call the Office Graph. The Office Graph is an intelligent fabric that combines machine learning to match the connections between people, content and interactions all across Office 365. Traditionally, we’ve had silos in the enterprise software, having loose connections between documents, users, emails, discussions, etc. Office Graph connects these entities together and organize them across your work. Office Graph then becomes a layer across Outlook, Yammer, One Drive for Business, etc. Office Graph simply connects these dots in the enterprise across the workloads. Office Graphs adds semantics and insights to the relationships making these things available to all the tools in Office 365 as well as any app that you create. SECURITY AND PRIVACY Office Graph respects security for whatever data source data comes from. You will never see anything in the Office Graph that you cannot see in the original system. You can see graph as a huge network where every user sees his part of the graph and is security-trimmed for that particular user. Some user actions and some relations are private and available only to the current user. Those actions may be aggregated in anonymous manner. For e.g. it shows a number of views on a particular document, but won’t show exactly which users. Authorship or editing a document is a public action, whereas viewing is private action. MICROSOFT GRAPH – UNIFIED API – HTTPS://GRAPH.MICROSOFT.COM This is an API on top of all other APIs, giving developers one coherent interface, one way of authenticating. In the past, you would have to use different authentication methods towards SharePoint, Outlook, etc. With unified API you can use one endpoint for all queries, which exposes data on REST. This is a strongly typed API. If you are dealing with a User, you are dealing with a User. If you are dealing with a Document, you are dealing with a Document. This allows different applications to work with a well-defined data model and a consistent way of working. MODELING CONCEPTS The modeling concepts in the Office Graph starts with a node. A node represents some entity with a stable ID, such as a user or document. The node has basic properties and navigation properties. A navigation property is an edge or pointer to another node. It has a type but no properties. A node may have multiple extensions (or views), each with a different set of properties describing some other aspect of the entity. We also have a special type of nodes as we call Action nodes. An action node has some properties that describe the action taken as well as the action and the object or object(s) in question. It can also have additional properties an edges that give more context such as the app used to take the action and similar. The Office Graph also can contain Relationship nodes. This how n-ary relationships and relationships with properties are represented. 2 Building solutions with Microsoft Graph Let’s say there are two nodes, a User and a File. These nodes are entities in the Graph. These nodes have a set of properties. So a User node could have a Name and an Alias and other properties as well. A file could have a Title, URL and an Author. In this case, Author is a navigation property. It’s a property that refers to another node, which is a User. Thus, it’s a pointer in the Graph. And when you look at any node in the Graph, that node could have multiple aspects or extensions. For e.g. a User can also be an Employee. Then we have action nodes, which then represents actions taken by User, and a typical action node will be TimeStamp, when this action was done, which User performed the action and what object the action was performed on. In addition, there will be a number of textual information as well, such as which action the User performed. https://msdn.microsoft.com/en-us/office/office365/howto/query-Office-graph-using-gql-with-search-rest-api REST AND ODATA Microsoft Graph API (https://graph.microsoft.com) provides programmatic access to Office 365 through an REST API endpoint, that support a wide range of OData operators. If you have experience consuming REST services and have a developer platform which allows you to make HTTPS requests, with open authorization tokens in request header, you can call Exchange Online, One Drive for Business and other services provided through Office 365 offering. https://graph.microsoft.com is the main URL for the entire family of Microsoft services. It can be used to interact with One Drive for Business, mailboxes, calendar, people, search, Office Graph, etc. from whatever device and platform you like. The API is consistent across multiple services and platforms. Following HTTP verbs or methods are permitted on the resource, to access and manipulate them. These correspond to create, read, update and delete (or CRUD). POST, GET, PUT, PATCH, and DELETE HTTP Verb CRUD Success Response Example POST Create Status Code: 201. Create a domain. Returns newly created object. GET Read Status Code: 200. Get domains Returns