List of all posts in the #30DaysMSGraph series
-Today’s post written by Srinivas Varukala
In Day 13 we discussed calling Microsoft Graph with Postman. Today we’ll look at the concept of batching that can help optimize your application by combining multiple Microsoft Graph queries.
JSON Batch Requests
Microsoft Graph allows you to combine multiple requests (using JSON batching) into one batch request thus helping optimize your application by reducing the number of requests/responses that goes back and forth. This makes your app less “chatty” and can save the application significant application latency.
For instance, before you load your application you want to fetch below details:
- User details (name, job title etc.)
- Get user’s manager
- List of planner tasks due for the user
- Upcoming meetings for the day
You can combine the above four requests into a single JSON batch request (i.e. single Microsoft Graph query) instead of sending out four separate Microsoft Graph queries.
NOTE: The requests that are batched should be independent and hence the order they appear in the JSON batch request should not matter.
Build your JSON batch request
Use the below sample/format to build your JSON batch request.
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me?$select=displayName,jobTitle,userPrincipalName "
},
{
"id": "2",
"method": "GET",
"url": "/me/manager "
},
{
"id": "3",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "4",
"method": "GET",
"url": "/me/calendar/events"
}
]
}
You can send the JSON batch request to Microsoft Graph using Graph Explorer along with the required request headers:
- POST https://graph.microsoft.com/v1.0/$batch
- Accept: application/json
- Content-Type: application/json
NOTE: The responses to the batched request might appear in a different order. The id property can be used to correlate the request/responses.
JSON Request Format
Batch requests are always sent using POST to the /$batch endpoint. The JSON batch request itself can contain both GET, POST, PATCH and other HTTP verbs that we discussed in this post [link to post].
JSON batch request body contains a single JSON object with one required property: “requests”. The requests property is an array of individual requests. Each individual request the “id”, “method” and “url” are the required properties.
Individual requests can optionally also contain a “headers” property and a “body” property. When a “body” is included with the request, the “headers” object must contain a value for “Content-Type”.
Response Format
The response format for a JSON batch request contains the main property called “responses”. Each individual response will have the “status” as a property that shows the HTTP status for the respective request.
There is a status code returned for the batch request itself, which is usually a 200 or 400 response. If the batch request is malformed, the status code returned is 400, otherwise the status code returned is 200.
In addition to the “responses” property, there might be a “netxtLink” property in the batch response. This works similar to the Paging using NextLink that is discussed in our previous post [link goes here]. This allows Microsoft Graph to return a batch response as soon as any of the individual requests has completed. You will have to continue to follow the “nextLink” as long as it exists.
Sequencing JSON requests using dependsOn property
You can specify dependencies on the requests in the JSON batch request using the “dependsOn” property. This property is an array of strings that reference the “id” of a different individual request. In the following request the second request has a dependency on the first one. This ensures the server processes the request with id value “1” first and then the second request. This example, the first request creates a folder called “TestBatchingFolder” in the users OneDrive and return it back in the second request.
{
"requests": [
{
"url": "/me/drive/root/children",
"method": "POST",
"id": "1",
"body": {
"name": "TestBatchingFolder",
"folder": {}
},
"headers": {
"Content-Type": "application/json"
}
},
{
"url": "/me/drive/root/children/TestBatchingFolder ",
"method": "GET",
"id": "2",
"DependsOn": [
"1"
]
}
]
}
NOTE: If an individual request fails, any request that depends on that request fails with status code “424” (Failed Dependency).
One advantage of using JSON batch request is that it helps you to bypass the URL length limitations when building complex and lengthy queries that might exceed the URL length limit built into browsers and other HTTP clients. With JSON batch these requests become part of the request payload thus bypassing the URL length limitations.
Try It Out
Navigate to the Graph Explorer. Execute the following commands.
- Create a batch request to get user profile picture, list of direct reports, list of calendar reminders for today (ex. Nov 13, 2018).
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me/photo/$value"
},
{
"id": "2",
"method": "GET",
"url": "/me/directReports"
},
{
"id": "3",
"method": "GET",
"url": "/me/reminderView(startDateTime='2018-11-13T08:00:00.0000000', endDateTime='2018-11-13T17:00:00.0000000')",
"headers": {
"Content-Type": "application/json"
}
}
]
}
- Assuming you got a list of your direct reports, now you can build another batch request to check their out of office settings. Below is a sample batch request. Be sure to replace <userID1@tenant>, etc. with the actual user UPN values returned from above query john@contoso.com.
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/users/<userID1@tenant>/mailboxSettings/automaticRepliesSetting"
},
{
"id": "2",
"method": "GET",
"url": "/users/<userID2@tenant>/mailboxSettings/automaticRepliesSetting"
},
…
…
]
}
Join us tomorrow as we look at building a .Net Core console application to make Microsoft Graph requests in Day 15.
