Microsoft Graph API – Part 3 – Customizing Queries for Results


This is our last article of 3 parts about Microsoft Graph API. In the first article, Microsoft Graph API – An Introduction, we had a quick overview of the Graph API and how it evolved from the Office Graph API. We also talked about what you need to know about setting up your endpoint API and tokens to build your custom solutions.

In part 2, Microsoft Graph API – Bringing it together, we showed you the structure of the Graph API that are composed of four layers: Data, Authentication and Authorization, Development Environment, and Solutions Layers. We also reviewed the importance of Active Directory and how organizations have started to build applications on the Graph API.

In this article, we will go a bit deeper in developing queries and syntax with the platform.

 

Common Microsoft Graph Queries 

Microsoft Graph API is currently available for preview only with two endpoint versions.  The first addresses users, groups, contacts, calendars, mail, and files.  The endpoint is https://graph.microsoft.com/v1.0 and is available for your production environment.  The second addresses tasks, people, OneNote, Excel, contacts (organization).  The endpoint is https://graph.microsoft.com/beta and is available for preview.  

Microsoft Graph API v1.0

Common queries that can be used to access the Microsoft Graph API is as follows:

Operation

Service endpoint

GET my profile

https://graph.microsoft.com/v1.0/me

GET my files

https://graph.microsoft.com/v1.0/me/drive/root/children

GET my photo

https://graph.microsoft.com/v1.0/me/photo/$value

GET my mail

https://graph.microsoft.com/v1.0/me/messages

GET my high importance email

https://graph.microsoft.com/v1.0/me/messages?$filter=importance%20eq%20'high'

GET my calendar

https://graph.microsoft.com/v1.0/me/calendar

GET my manager

https://graph.microsoft.com/v1.0/me/manager

GET last user to modify file foo.txt

https://graph.microsoft.com/v1.0/me/drive/root/children/foo.txt/lastModifiedByUser

GET unified groups I’m member of

https://graph.microsoft.com/v1.0/me/memberOf/$/microsoft.graph.group?$filter=groupTypes/any(a:a%20eq%20'unified')

GET users in my organization

https://graph.microsoft.com/v1.0/users

GET group conversations

https://graph.microsoft.com/v1.0/groups/<id>/conversations

Source:  https://graph.microsoft.io/en-us/docs

Microsoft Graph API Beta

Queries that are available in the beta version are as follows, but is important to note that they are in beta and it is not suggested that these be applied in the production environment:

Operation

Service endpoint

GET people related to me

https://graph.microsoft.com/beta/me/people

GET files trending around me

https://graph.microsoft.com/beta/me/trendingAround

GET people I am working with

https://graph.microsoft.com/beta/me/workingWith

GET my tasks

https://graph.microsoft.com/beta/me/tasks

GET my notes

https://graph.microsoft.com/beta/me/notes/notebooks

Source:  https://graph.microsoft.io/en-us/docs

 

Syntax Patterns

For developers, the syntax patterns, at this time of publication, are as follows:

1.  Microsoft Graph API Endpoint:

{Graph Endpoint} https://graph.microsoft.com

2.  Target Service Version: 

{Version} such as v1.0 or beta

3.  Tenant Name or Specific Entities: 

{Tenants} such as users, groups, files

4.  Particular Item from Entity Set: 

{Id} such as single user and file

5.  Specific Property of Particular Object Selected from Entity Set: 

{Property}

Query Parameters

Microsoft Graph API supports the following query options which allow you to specify and control the amount of data that is returned in a response: 

  1. $Select – include in response comma separated list of properties:  https://graph.microsoft.com/v1.0/me/messages?$select=from,subject
  2. $Expand – include in response expanded comma separated list of relationships:  https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)
    Note: maximum number of expanded objects for a request is 20 and if the query is placed on the user resource, the properties of only one child object or collection can be retrieved at a time. 
  3. $OrderBy – include in response comma separated list of properties used to sort order of items in response collection: https://graph.microsoft.com/v1.0/users?$orderBy=displayName%20desc(asc)
  4. $Filter – filters response based on a set of criteria:

    1. By name: https://graph.microsoft.com/v1.0/users/?$filter=startswith(displayName,{Name})
    2. By entity type: https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address%{Value}eq%{EmailAddress}%27
  5. $Top – Number of items to return in a result set: https://graph.microsoft.com/v1.0/users?$top={Number}
  6. $Skip – Number of items to skip in a result set:  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip={Number to be skipped}
  7. $skipToken – paging token used to get next set of results:

    1. https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skiptoken=X%{value}%
    2. To return the next page of users within your organization, the syntax is: https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skipTokes =%{value}
  8. $Count – A collection and the number of items in the collection: https://graph.microsoft.com/v1.0/me/contacts?$count=true
  9. $directReports – Gets user objects, each with up to 20 directReport objects in the directReports collection: https://grap.microsoft.com/v1.0/users?$expand=directReports

By applying custom queries and setting specific parameters, Microsoft Graph API can be customized to provide tailored solutions to your corporation on a platform of your choice, including Android, Windows, and iOS.

Microsoft Graph API is an excellent solution from Microsoft to meet the demands of businesses in today’s world of cloud computer based business.  Flexible, seamless and efficient, Microsoft Graph API is the solution for obtaining aggregate data from various Microsoft cloud-based services including SharePoint, SharePoint Mobile, Office 365, Outlook, Calendar and social media apps such as Twitter and Yammer.

 

Microsoft Graph API – Part 2 – Bringing it Together


In our first Part, Microsoft Graph API – An Introduction, we reviewed the evolvement of Office Graph into Microsoft Graph API.  We also looked at the reasons as to why a change in process for accessing data was required.  Next, we delved into how the transition of obtaining aggregate data from various cloud services with a complex system of individually specific APIs and multiple tokens became one singular endpoint API and one token.  Customizing app solutions has become easier with a single endpoint API, and the possibility to provide these solutions in Windows, Android, and iOS platforms is becoming a reality with the move to open source developer tools.   

The Structure of Microsoft Graph API Developer Stack

In order to develop applications based on Microsoft Graph API, a basic understanding of the developer stack in needed.  There are four layers:

1.  Data Layer: 

Office Graph and Microsoft Graph API reside in this layer.  Information regarding people, emails, notes, documents and relationships with each other is delivered from this layer. 

2.  Authorization and Authentication Layer: 

Authorization and authentication use OpenID Connect and OAuth2.0 to perform these functions.

3.  Development Environment Layer: 

Software Development Kits (SDK) for Windows, iOS, and Android reside in this layer.  Development tools such as Visual Studio, XCode, Eclipse, Android Studio and REST (Representational State Transfer) are available in this layer.

4.  Solution Layer: 

Your app or solution is deployed from this layer on either Microsoft Azure or on other hosting platforms such as LAMP and IIS while enabling the developer to use their choice of language such as .NET, JS, HTML, and Ruby depending upon the apps solution that is being targeted (Windows, Android or iOS). 

This is best illustrated in the infographic below (source: https://graph.microsoft.io/en-us/docs).

Microsoft Graph API Developer Stack

Microsoft Graph API Developer Stack – Illustration

 

The Importance of the Microsoft Active Directory (AD)

Microsoft Active Directory (AD) is a structure used on computers and servers running a Windows operating system.  The primary function of the AD is to store network, domain and user information, such as user accounts, passwords, and profiles, in a single, protected location.

The AD is only as useful as the information that has been submitted and entered.  The importance of having a complete and accurate user profile is the key to successfully accessing user and business information.  For many corporations, the AD is lacking substance and with the lack of key information, collaboration, communication, and efficiency is greatly decreased with collaboration tools such as SharePoint, Delve, and business processes built on flow. Achieving AD compliance has always been a challenge for organizations with the lack of Governance and AD maintenance. This particular issue is being addressed by Hyperfish.   

Recognizing this as a point of need for businesses, Hyperfish was developed to achieve corporate compliance with each user by interactively engaging the user to complete the necessary information fields.  Hyperfish monitors the AD, or the Azure Active Directory (AAD) for missing, incomplete or out of date information.  After analysis, the system will then contact the user at the most appropriate time and method to elicit responses from the user to complete their profile.  The user will be prompted with suggestions which are based on information gathered from email, social media, and other data sources.  An AD that is complete will improve the quality and speed of communication between team members, and can be combined with Workflow, Office 365, SharePoint and SharePoint Mobile to maximize the effectiveness of collaboration. 

The Microsoft Active Directory serves as the hub of corporate user information, allowing administrators to set rules and trusts according to teams and privileges and when populated correctly, provides pertinent information which ensures utmost proficiencies in collaboration and communication.

Our last part will be an in-depth look at the most common Microsoft Graph API queries, syntax standards and parameter settings in Microsoft Graph API – Customizing Queries for Results. 

 

Microsoft Graph API – An Introduction


What is Microsoft Graph API?

Microsoft Graph API (Application Programming Interface) is the evolvement of Office 365 Unified API into a single stop for a cloud solution by exposing multiple Microsoft cloud service APIs through a single REST (Representational State Transfer) API endpoint. Microsoft Graph API provides seamless navigation between service entities such as users, groups, mail, messages, notes, tasks, and calendar, and Office Graph. Data can be accessed from multiple Microsoft cloud services such as Exchange, OneDrive, SharePoint, OneNote, Planner and Azure Active Directory.

As business and society move towards storing and accessing data in the cloud, the increase in traffic and increase in data volume results in data congestion. This translates into lost productivity, delays in decisions and miscommunication between groups and management. With each step towards cloud-based computing and collaboration, Microsoft is addressing the issue of cloud data congestion with Microsoft Graph API.
 

What is the Difference Between Office Graph and Microsoft Graph API?

When we examine Microsoft cloud services, we can see services that include SharePoint Mobile, Office 365, OneDrive, Outlook, Calendar, Skype, and Yammer. Each of these services is used to manage documents, email, events, collaboration and social interactions. These services can then be viewed as two types of entities: content and communication.

Let’s back up a bit to fully understand how Microsoft Graph API works. Before API, there was Office Graph. Office Graph was developed to link the two entities of content and collaboration together. Imagine the user centrally located on a blank page. As the user connects to various content and communicates with team members, a thin spider web connects the user with each action thus creating a web of all his actions and relationships to users around him. This spider web network shows the direct and indirect relationships the user within his work environment and how he responds and actions out his responses and questions.

With machine learning algorithms built into Office Graph, the user’s daily activity and the relationships between nodes, such as who the user reports to, who the colleagues of the user are, which documents are most frequented by the user, and so on, can be determined. By collecting and analyzing, this algorithm allows Office Graph to learn the user’s most frequented services and bring them to the top of the page for easy access.

With Office Graph, the user has created a web that consists of content and communication. Each piece of content is a node. Each person is a node. Each form of communication is a node. Office Graph connects these nodes together through specific APIs. Each one has its own API. Office Graph creates a small web for each user, whereas, Microsoft Graph API creates a web not only for one user but interlinks related users across an entire organization resulting in a large web of collaboration and communication.

Here is an image that shows how we can use Office Graph to connect and surface data among different areas of the Office 365 and Azure stacks.

Office Graph

The larger the web, the slower the time to access and find data. Microsoft Graph API retained the inherent machine learning capabilities as one of the responses to this issue. By collecting and analyzing, the machine learning algorithm allows Microsoft Graph API to learn the users working relationships and brings to the forefront the most frequented services not only for each individual user but as an organization as a whole by connecting each individual with collaborators and teams.

The single and greatest response to cloud data congestion is that Microsoft Graph API was evolved further so that multiple API exposures from Microsoft Cloud services are handled through a single REST API end point. In other words, there is one endpoint to rule them all!
 

How does Microsoft Graph API work?

In Office Graph, data in Office 365 is filed in individual silos. These standalone silos are labeled users, groups, files, mail, calendar, contacts, tasks, people, Excel and insights and relationships. Each silo has it very own unique API which caused a challenge for developers to access the data and eventually, it became cumbersome due to the complexity of accessing the individual APIs for different types of data and linking them to each other in different services. For example, accessing users and people in Azure Active Directory required one set of rules while accessing users and people in SharePoint required a second set of rules. In addition, separate access tokens had to be created to access data from different data silos. This was time intensive and not clean methodology! And so, Microsoft Graph API was born.

Microsoft Graph API provides access to Office Graph data with a single endpoint to display the data in your cloud app. Gone are the days of multiple tokens. With Microsoft Graph API, only a single access token is required regardless of which Microsoft cloud service that information is being retrieved from. Microsoft Graph API provides sleek, seamless and efficient access to information when you need it and how you need it.

Microsoft Graph API

In short, Microsoft Graph API provides a unified REST API endpoint, https://graph.microsoft.com, for accessing aggregated data from multiple Microsoft cloud services in a single response by using a single authentication token. Yes, it’s that simple.

In Part 2, Microsoft Graph API – Bringing it Together, we will delve into the developer stack and the importance of having a substantial Microsoft Active Directory. In our last Part (3), we will look closely at the common Microsoft Graph API queries in Microsoft Graph API – Customizing Queries for Results.