List of all posts in the #30DaysMSGraph series
In Day 5 we began discussing the query parameters available for Microsoft Graph requests. Today we’ll continue looking at query parameters available for requests against Microsoft Graph.
Count
Count is a useful query parameter to use when your app needs to know the number of records that exist for a given endpoint. The count of records will be returned as a property.
Syntax
<baseGraphQuery>?$count=<boolean>
Ex. – Get number of contacts for the logged in user
https://graph.microsoft.com/v1.0/me/contacts?$count=true
Top
Queries to Microsoft Graph sometimes have more records in the result than can be returned in a single response. You can use the Top query parameter to set the maximum number of results to be returned.
Syntax
<baseGraphQuery>?$top=<int>
Ex. – Get the logged in user’s OneNote notebooks, 2 per page
https://graph.microsoft.com/v1.0/me/onenote/notebooks?$top=2
Skip
Skip is another query parameter primarily used when paging results back from Microsoft Graph. An @odata.nextlink will typically contain a Skip or SkipToken query parameter. When used by itself a Skip query parameter will skip the first N number of items in the results.
Syntax
<baseGraphQuery>?$skip=<int>
Ex. – Get the logged in user’s emails starting with the 11th email
https://graph.microsoft.com/v1.0/me/messages?$skip=10
Search
Search is like Filter in that you are restricting the response to a subset of results. Search has the benefit of allowing for free-text search expressions at the cost of only being available for the “message” and “person” resources.
Syntax
<baseGraphQuery>?$search=<searchCriteria>
Ex. – Get the logged in user’s emails that contain the word “Contoso” in the message body
https://graph.microsoft.com/v1.0/me/messages?$search=”body:Contoso”
Expand
As mentioned on Day 4, many times entities on Microsoft Graph will have relationships to each other. Use the Expand query parameter to return more information about complex data types or related entities.
Syntax
<baseGraphQuery>?$expand=<property>
Ex. – Get expanded information for logged in user’s manager
https://graph.microsoft.com/beta/me?$expand=manager
Note: this example uses the beta endpoint as User entities only support the Expand query parameter on the beta version of APIs as of time of writing (Nov 2018).
Try It Out
Use query parameters we covered today to count, search, expand, and restrict results. Navigate to the Graph Explorer. Execute the following commands.
- Get number of contacts for the logged in user
- Get the logged in user’s OneNote notebooks, 2 per page
- Get the logged in user’s emails starting with the 11th email
- Get the logged in user’s emails that contain the word “Contoso” in the message body
- Get expanded information for logged in user’s manager
Join us tomorrow as we review paging Microsoft Graph result sets in Day 7.
