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.

 

  • Monday, October 31, 2016 By : Mike Maadarani   

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    captcha

    Please enter the CAPTCHA text

    0 comment