30DaysMSGraph – Day 6 – Query Parameters Part 2

Brian T. Jackett

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 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.

Day 6 repo link

  1. Get number of contacts for the logged in user
  2. Get the logged in user’s OneNote notebooks, 2 per page
  3. Get the logged in user’s emails starting with the 11th email
  4. Get the logged in user’s emails that contain the word “Contoso” in the message body
  5. Get expanded information for logged in user’s manager

 

Join us tomorrow as we review paging Microsoft Graph result sets in Day 7.

Feedback usabilla icon