M365 – Microsoft Graph – Optimize data usage when using Microsoft Graph with query parameters

Hi All,

LIFE IS BEAUTIFUL 🙂 I hope we all are safe:) STAY SAFE, STAY HEALTHY 🙂 STAY HOME 🙂

Knowledge Junction have good series of Microsoft Graph so continuing that since this is one of my favorite topic and of Microsoft also 🙂

If you are beginner for Microsoft Graph, please go through our whole series – https://knowledge-junction.in/?s=Microsoft+Graph

Microsoft Graph provides unified programming model for developers to build applications.

Microsoft Graph REST APIs implements lots of OData protocols query parameters.

In this article we will discuss how to manipulate queries using query parameters.

Take away from this article:

• How to use REST queries with query parameters
• Queries for expanding complex entities
• Using search to search the content using Microsoft Graph
• Batching of queries

Prerequisite:

• Basic knowledge of REST queries
• Experience with Visual studio Code at beginner level
• Access to Microsoft 365 tenant

When we develop applications using Microsoft Graph we have two options to choose to use Microsoft Graph

• Microsoft Graph REST APIs
  • Microsoft Graph is nothing but REST API.
  • When we use REST API means we can use any platform, any framework or any programming language.
  • We just need to fire HTTP request and need to process HTTP response
• Microsoft Graph Native SDK
  • SDKs are abstraction to the REST APIs
  • SDKs are available for various platform including .NET, iOS, Android, Java, PhP, Ruby, JavaScript, and many more.

Using Query Parameters with Microsoft Graph Requests:

• Microsoft Graph REST APIs support many query parameters.
• Query parameters basically allows us /developers to limit the data which is returned in response of query
• Limiting the number of returned result using $top : The $top parameter allows us to limit number of result in response. In below example we are fetching only 50 users

https://graph.microsoft.com/v1.0/users?$top=50

• Requesting paged results : Some of the Microsoft Graph Queries returns result in multiple pages. Pages of data either is returned due to server-side implementation of paging or use of $top parameter in the query parameter to limit the result in request. When result comes in multiple pages Microsoft Graph returns $odata.nextLink property in response that contains the URL for next page

For example, in following query we are requesting 2 users but in my local tenant we are using there are more than 2 users so we will get the link to next page

https://graph.microsoft.com/v1.0/users?$top=1
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=2&$skiptoken=X%2744537074020001000000293A4D616E6173406B6E6F776C656467656A756E6374696F6E312E6F6E6D6963726F736F66742E636F6D29557365725F63383430386432392D646534312D343638612D613634662D386362346131343835663266B900000000000000000000%27",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Ganesh",
            "givenName": "Ganesh",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": "Gade",
            "userPrincipalName": "Ganesh@knowledgejunction1.onmicrosoft.com",
            "id": "9cf4fe0c-d572-4689-8879-f1d5099075a4"
        }
    ]
}

In above response there is next page link as

“@odata.nextLink”: “https://graph.microsoft.com/v1.0/users?$top=2&$skiptoken=X%2744537074020001000000293A4D616E6173406B6E6F776C656467656A756E6374696F6E312E6F6E6D6963726F736F66742E636F6D29557365725F63383430386432392D646534312D343638612D613634662D386362346131343835663266B900000000000000000000%27”

when we will hit this link in query we will get the next page result as

Microsoft Graph will continue to return a reference to the next page link of data in the @odata:nextLink property with each response until all pages of the result have been read.

• Fetching specific fields in result using $select parameter : By default Microsoft Graph query response returns all default properties/fields. But if we requires only say Email or UserName then why to get all these fields in response which will cause poor performance. To optimize the performance we can use $select parameter to specify the fields/properties which we want

https://graph.microsoft.com/v1.0/users?$select=displayName, mail, userPrincipalName

• Ordering the result : Result in response can be order by using $orderby parameter. Following query orders the result based on displayName property/field as

https://graph.microsoft.com/v1.0/users?$orderby=displayName

By default data is returned in ascending order but with desc keyword we can sort the result in descending order as

https://graph.microsoft.com/v1.0/users?$orderby=displayName desc

• Expand related entities in queries : We can use $expand operator, to expand collection of items. Lets have a scenario where we need to get the only members of O365 Groups.

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

Here, in above query without $expand parameter, we will get all groups but then we need to iterate through all the groups and get the members details. But we $expand query we can get member details in query as

https://graph.microsoft.com/v1.0/groups?$expand=members

Limit query result using $filter query parameter : This is another optimization option. With $filter option we can limit the size of response by applying filtering on specific content. Lets consider the scenario where we need to filter all the users starting with displayName = prasham sabadra as

https://graph.microsoft.com/v1.0/users?$filter=displayName eq 'prasham sabadra'

$filter query parameter supports following logical operators:

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

Using Search with Graph REST APIs : $search query parameter is used to search the content against People and Message. Consider the scenario where we need to find all messages which having subject contains the “Your preview of the new Briefing email” as

https://graph.microsoft.com/v1.0/me/messages?$search="subject:Your preview of the new Briefing email"

But search has some limitations. It only returns 250 results. We can not use search with $filter and $orderby query parameters.

• Batched Request: Batching is the process to execute multiple requests, group them in single request and return the grouped result for each request in single response. Important point to note here is Batching does not reduce the number of requests but reduces the number of HTTP round trips

Batched query is POST request.

Consider a simple scenario, where I need to fetch my details (current user details) as well as my messages (current users messages), here I could batch these two request in single request and get result in single response as

https://graph.microsoft.com/v1.0/$batch

Request Body:

{
    "requests": [
        {
            "url": "/me?$select=displayName,jobTitle,userPrincipalName",
            "method": "GET",
            "id": "1"
        },
        {
            "url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview",
            "method": "GET",
            "id": "2"
        }
    ]
}

Response Body:

{
    "responses": [
        {
            "id": "2",
            "status": 200,
            "headers": {
                "Cache-Control": "private",
                "OData-Version": "4.0",
                "Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
            },
            "body": {
                "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('ff594132-b1a6-4bd3-92e5-1d4621ca9180')/messages(from,subject,receivedDateTime,bodyPreview)",
                "value": []
            }
        },
        {
            "id": "1",
            "status": 200,
            "headers": {
                "Cache-Control": "no-cache",
                "OData-Version": "4.0",
                "Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
            },
            "body": {
                "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,jobTitle,userPrincipalName)/$entity",
                "displayName": "Prasham Sabadra",
                "jobTitle": null,
                "userPrincipalName": "prasham@knowledgejunction1.onmicrosoft.com"
            }
        }
    ]
}

In above query, we combined two queries in one request and got the two results in one response. Now how the result is identified that which result is for which query by using the value of “id” attribute. If you notice both response and result header there is common value for “id” attribute.

Also one more point to note is, here sequence of queries in Request object dosent matters. The query which is executed fast which appears on the top in response object. In above scenario, we have second query result is on the top.

Since these above both the queries are not related we can not use the $expand query parameter as well.

We have an alternative of dependsOn parameter, to specify the order. For example consider above scenario again where we want to execute the first query first and then only second query then we can specify depends on parameter in second query as

Using "DependsOn: parameter in second query of below requests
{
    "requests": [
        {
            "url": "/me?$select=displayName,jobTitle,userPrincipalName",
            "method": "GET",
            "id": "1"
        },
        {
            "url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview&$top=1",
            "method": "GET",
            "id": "2",
            "DependsOn": [
                "1"
            ]
        }
    ]
}

Response below:
{
    "responses": [
        {
            "id": "1",
            "status": 200,
            "headers": {
                "Cache-Control": "no-cache",
                "OData-Version": "4.0",
                "Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
            },
            "body": {
                "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,jobTitle,userPrincipalName)/$entity",
                "displayName": "Prasham Sabadra",
                "jobTitle": null,
                "userPrincipalName": "prasham@knowledgejunction1.onmicrosoft.com"
            }
        },
        {
            "id": "2",
            "status": 200,
            "headers": {
                "Cache-Control": "private",
                "OData-Version": "4.0",
                "Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
            },
            "body": {
                "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('ff594132-b1a6-4bd3-92e5-1d4621ca9180')/messages(from,subject,receivedDateTime,bodyPreview)",
                "value": []
            }
        }
    ]
}

Other important point to note here is batching dosent support the transactions .

What Next in Graph Articles? – In next Graph article we will discuss about throttling in Microsoft Graph.

Thanks for reading 🙂 If its worth at least reading once, kindly please like and share. SHARING IS CARING 🙂

Enjoy beautiful life 🙂 Have a FUN 🙂 HAVE A SAFE LIFE 🙂 TAKE CARE 🙂