Post
Ask Question

Using Optional Query Parameters With Microsoft Graph API - Part Two

In this article, I will continue showing how to execute the calls to Microsoft Graph API using some optional OData query parameters.

The part-1 of this article series can be found here. Let’s now see the remaining query parameters one by one.

$select

Explanation

When you fire an API call to MS Graph, it will return the JSON result with all the properties. You may not need all the properties of a result set always. When you want MS Graph API to return only certain properties, then use $select parameter to specify which properties you want in result set. 

Please note that the no. of records in the result will not be affected with or without $select parameter, only what’s returned for each record in result will change.

Example

Open MS Graph Explorer here and fire the following call to get a list of files from OneDrive:

  • https://graph.microsoft.com/v1.0/me/drive/root/children or click here, then press “Run Query”

See the data returned in JSON response.

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.   "createdBy": {  
  3.     "user": {  
  4.       "displayName": "Megan Bowen"  
  5.     }  
  6.   },  
  7.     "createdDateTime": "2017-07-31T18:56:29Z",              
  8.     "id": "01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K",              
  9.     "lastModifiedDateTime": "2017-07-31T18:56:29Z",  
  10.     "name": "Attachments",              
  11.     "folder": {  
  12.         "childCount": 0  
  13.     },  
  14.     "size": 0              
  15. },  
  16. {  
  17.   "createdBy": {  
  18.     "user": {  
  19.       "displayName": "Megan Bowen"  
  20.     }  
  21.   },  
  22.   "createdDateTime": "2017-08-07T16:18:24Z",    
  23.   "id": "01BYE5RZ4CPC5XBOTZCFD2CT7SZFNICEYC",    
  24.   "lastModifiedDateTime": "2017-08-07T16:18:24Z",  
  25.   "name": "Contoso Clothing",      
  26.   "folder": {  
  27.     "childCount": 14  
  28.   },  
  29.   "size": 5912877  
  30. }  

Out of all these properties, what may be most important for you if you wanted to show the user his/her files from OneDrive? Of course, the name of the file/folder.

Fire following call in MS Graph Explorer to get only file name in result.

  • https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name or click here, then press “Run Query”

You will see the following result.

Office Development

Following is the result JSON snippet containing some of the values.

  1. {    
  2.   "value": [  
  3.     {  
  4.       "@odata.etag": "\"{60F36ED0-85CE-4771-B349-E671C691EFCA},1\"",  
  5.       "name": "Attachments"  
  6.     },  
  7.     {  
  8.       "@odata.etag": "\"{A9D9C2AC-FF32-42EE-87C3-283CFCE061E1},1\"",  
  9.       "name": "Business Data"  
  10.     },  
  11.     {  
  12.       "@odata.etag": "\"{73E9E609-FA05-42D8-82BD-1239D821CDD8},1\"",  
  13.       "name": "Class Documents"  
  14.     }  
  15.   ]  
  16. }  

Now, MS Graph API returns only file/folder name, instead of all the details. (Of course, “etag” is included but ignore it)

You can also use more than one property separated by comma, e.g.

  • https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name,size

And, you will get the following result.

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.   "value": [  
  3.     {  
  4.       "@odata.etag": "\"{60F36ED0-85CE-4771-B349-E671C691EFCA},1\"",  
  5.       "name": "Attachments",  
  6.       "size": 0  
  7.     },  
  8.     {  
  9.       "@odata.etag": "\"{A9D9C2AC-FF32-42EE-87C3-283CFCE061E1},1\"",  
  10.       "name": "Business Data",  
  11.       "size": 39566226  
  12.     }  
  13.   ]  
  14. }  

If you type in the property that does not exist in the result set, then it will be ignored.

e.g. - fire the following call and see what happens:

  • https://graph.microsoft.com/v1.0/me?$select=salary

Usage

In your programming, you can use $select query parameter to,

  • Get only specific property in result set (to make efficient use of bandwidth)
  • Specify those properties not returned in default result set

$search

Explanation

Using $search query parameter, you can specify free text search criteria for items being returned in result set. Please note that this parameter is currently supported for only “messages” and “person” entities. Microsoft Graph team will cover more entities later.

Some programmers are confused between $search and $filter parameters because both do similar operations. I will explain the difference briefly in the next section for the $filter.

When you specify $search parameter, it tells MS Graph API to include only those entities in the result which match the specified expression. Here what to match is left for the implementer, OData specification does not mandate anything. Hence when you specify search criteria with $search query parameter, the result will be dependent on what MS Graph API team has decided to implement. Mostly it works as free text search.

Example

Let’s say you want to find out emails which have “brainstorming” mentioned somewhere.

Open MS Graph Explorer here and fire the following call.

  • https://graph.microsoft.com/v1.0/me/messages?$search=brainstorming or click here, then press “Run Query”

See the data returned in JSON response.

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.     "value": [  
  3.       {  
  4.         "createdDateTime": "2017-09-08T05:57:44Z",  
  5.         "lastModifiedDateTime": "2017-09-08T05:57:45Z",          
  6.         "hasAttachments": false,          
  7.         "subject": "DG2000+ Brainstorming Session",  
  8.         "bodyPreview": "Hello Product Launch Team...",  
  9.         "importance": "normal",          
  10.         "sender": {  
  11.           "emailAddress": {  
  12.             "name": "Miriam Graham",  
  13.             "address": "[email protected]"  
  14.           }  
  15.         },          
  16.         "ccRecipients": [],  
  17.         "bccRecipients": [],  
  18.         "replyTo": []  
  19.       }  
  20.     ]  
  21. }  

Graph API will match the word brainstorming in an email’s from, subject and body fields, and will show the matching messages in the result.

Let’s see another example of using $search with “people” entity.

Open MS Graph Explorer here and fire following call:

  • https://graph.microsoft.com/v1.0/me/people?$search=langer or click here, then press “Run Query”

See the data returned in JSON response.

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.     "value": [  
  3.       {  
  4.         "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",  
  5.         "displayName": "Isaiah Langer",  
  6.         "givenName": "Isaiah",  
  7.         "surname": "Langer",  
  8.         "jobTitle": "Web Marketing Manager",          
  9.         "department": "Sales & Marketing",          
  10.         "phones": [  
  11.           {  
  12.             "type": "business",  
  13.             "number": "+1 918 555 0101"  
  14.           }  
  15.         ]  
  16.       }  
  17.     ]  
  18. }  

MS Graph API will search for the people related to the sample account user, will search for “langer” in display name or email, and will return matching records in result.

There are many more possible calls using the $search parameter, but I will restrict to these two calls only for brevity. I encourage you to explore more by yourself.

Usage

In your programming, you can use $search parameter to:

  • perform a free text search on messages or people related to user
  • perform fuzzy searches on people

$filter

Explanation

With $filter parameter, you can specify the filter criteria on a result set using logical operators or string functions. There are fixed logical and string operations which can be performed on a result set using $filter function.

The following extract is taken from the OData specification website here

The $filter system query option allows clients to filter a collection of resources that are addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.

Let’s understand the difference between $search and $filter parameters,

  • $search starts with an empty result set and adds items to it based on criteria that match, while $filter takes full result set, and removes items based on criteria that don't match.
  • $search operates like a free text search, while $filter works on predefined logical and string functions.

Which logical and string functions are supported with $filter?

As per current MS Graph API documentation, following functions are supported, but the support varies as per which entity you are dealing with, so always refer to latest documentation on Microsoft site:

  • equals (eq)
  • not equals (ne)
  • greater than (gt)
  • greater than or equals (ge)
  • less than (lt), less than or equals (le)
  • and (and)
  • or (or)
  • not (not)
  • startswith
  • any

Example

Let’s see some examples of how you can use $filter parameter.

Open MS Graph Explorer here and fire the following call:

  • https://graph.microsoft.com/v1.0/me/people?$filter=jobTitle eq null or click here, then press “Run Query”

See the data returned in JSON response, it returns all “users” associated with the sample account whose job title is not set,

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.     "value": [  
  3.       {  
  4.         "displayName": "Marketing",  
  5.         "jobTitle": null  
  6.       },  
  7.       {              
  8.           "displayName": "Product Launch Event",           
  9.           "jobTitle": null  
  10.       },  
  11.       {              
  12.           "displayName": "Retail",              
  13.           "jobTitle": null  
  14.       },  
  15.       {              
  16.           "displayName": "Tailspin Toys",           
  17.           "jobTitle": null  
  18.       },  
  19.       {  
  20.         "displayName": "Activewear",  
  21.         "jobTitle": null  
  22.       }     
  23.     ]  
  24. }  

Similarly, if you want to see only those records where job title is set, then simply change the operator “eq” (for equal to) to “ne” (for not equal to)

  • https://graph.microsoft.com/v1.0/me/people?$filter=jobTitle ne null&$select=jobTitle,displayName or click here, then press “Run Query”

You will see the following response which will list all users who have job title assigned,

Office Development

Following is the result JSON snippet containing some of the values.

  1. {  
  2.     "value": [  
  3.       {  
  4.           "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",  
  5.           "displayName": "Isaiah Langer",  
  6.           "jobTitle": "Web Marketing Manager"  
  7.       },  
  8.       {  
  9.         "id": "48d31887-5fad-4d73-a9f5-3c356e68a038",  
  10.         "displayName": "Megan Bowen",  
  11.         "jobTitle": "Auditor"  
  12.       },  
  13.       {  
  14.           "id": "f5289423-7233-4d60-831a-fe107a8551cc",  
  15.           "displayName": "Ben Walters",  
  16.           "jobTitle": "VP Sales"  
  17.       }   
  18.     ]  
  19. }  

Please note here that you see only 2 properties in the response because I also used the $select parameter in the API call. You can use “&” in an API call when you want to use more than one optional query parameter,

Office Development

https://graph.microsoft.com/v1.0/me/people?$filter=jobTitle ne null&$select=jobTitle,displayName

There are much more uses of $filter parameter possible, but I will restrict to only two examples for brevity. I suggest you read more on Microsoft Graph API documentation page here.

Usage

Use the $filter parameter in your programming to,

  • make API calls with logical operations for checking equality, greater than, less than, etc. operations

$skipToken

Explanation

When a response from MS Graph API does not contain all the available records (due to the user explicitly specifying to select only some top records or due to server-side paging implemented in Graph API to limit response size), then you will see the response contains a server generated value with the $skipToken parameter. This value is to be specified in the next call to MS Graph API so that it will return the next set of records. The value of $skipToken is generated by the server, it can not be specified by you as a consumer.

Example

Fire the following call to get only top 10 files stored on user’s OneDrive,

  • https://graph.microsoft.com/v1.0/me/drive/root/children?$top=10 or click here, then press “Run Query”

See the result, note the value in @odata.nextLink property,

Office Development

Following is the result JSON snippet containing some of the values,

  1. {  
  2.   "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('48d31887-5fad-4d73-a9f5-3c356e68a038')/drive/root/children",  
  3.     
  4. "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/root/children?$top=10&  
  5.   $skiptoken=Paged%3dTRUE%26p_SortBehavior%3d0%26p_FileLeafRef%3dAll%2520Japan%2520Revenues%2520By%2520City%252exlsx%26p_ID%3d33%26p_FileDirRef%3dpersonal%252fmeganb%255fm365x214355%255fonmicrosoft%255fcom%252fDocuments%26RootFolder%3d%252fpersonal%252fmeganb%255fm365x214355%255fonmicrosoft%255fcom%252fDocuments",  
  6.   "value": [  
  7.     {  
  8.       //data cleared for brevity  
  9.     }  
  10.   ]  
  11. } 

The @odata.nextLink property contains the call which should be fired to get the next set of result. For identifying what should be returned, it has a skip token generated from server-side with some logic to skip those records in current response.

Simply fire the query mentioned in the @odata.nextLink property, and you will get next set of values.

Usage

  • In your programming, you can use $skipToken to get paginated data (implement paging).

Limitations/Errors

Not all query parameters are supported for all entities. Always refer to latest Microsoft documentation for what’s supported. I also suggest firing the call in MS Graph Explorer first and see if you are getting the expected result or not, before starting any programming and later having any surprise.

If you include some query parameter for a non-supported entity, then MS Graph API will throw an appropriate error.

Let’s understand with an example.

Fire the following call in MS Graph Explorer:

  • https://graph.microsoft.com/v1.0/users?$filter=123 or click here, then press “Run Query”

You will get error 400,

Office Development

Following is the result JSON snippet containing some of the values,

  1. {  
  2.   "error": {  
  3.     "code": "BadRequest",  
  4.     "message": "Invalid filter clause",  
  5.     "innerError": {  
  6.       "request-id": "c19b6fbb-e3f4-4007-a012-eac483100272",  
  7.       "date": "2017-11-13T18:41:25"  
  8.     }  
  9.   }  
  10. } 

Using query parameter without ‘$’ prefix in beta version of MS Graph API

With beta version of MS Graph API, using “$” prefix before a query parameter is optional.

Fire following call in MS Graph Explorer to get top 2 recently accessed files in result,

  • https://graph.microsoft.com/beta/me/drive/recent?top=2 or click here, then press “Run Query”

You will see the following result,

Office Development

Following is the result JSON snippet containing some of the values,
  1. {  
  2.   "value": [  
  3.     {  
  4.       "@odata.type": "#microsoft.graph.driveItem",   
  5.        "id": "01BYE5RZ2KXWOTNNU3K5B3AZ4YMANXEMAE"          
  6.     },  
  7.     {  
  8.       "@odata.type": "#microsoft.graph.driveItem",        
  9.       "id": "01BYE5RZZ5OJSCSRM6BZDY7ZEFZ3NJ2QAY"          
  10.     }  
  11.   ]  
  12. }  

Note that the “top” query parameter is used without any “$” prefix here and still you get only 2 records in result.

This concludes my 2-part article series on MS Graph API query parameters. I hope you enjoyed learning about how to use query parameters in the MS Graph API call.

I suggest you keep reading more about MS Graph API until my next article (part-3).  

You can read some of my articles on MS Graph API and Office 365 development here.


Similar Articles