Delta query for Users, Groups, Messages, Calendar, and more, available in preview

Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights, via a number of resources like users and messages. Many applications need to keep track of what’s changing in these data sets, and we recently added support for delta query   across a variety of resources on our /beta endpoint to help make that easier. These include Users, Groups, Messages, Mail Folders, Calendar Events, Personal Contacts, and Contact Folders.

So what is Microsoft Graph delta query? This capability enables applications to discover newly created, updated, or deleted resources and relationships without performing a full read with every request. delta query also provides change tracking for relationships between these entities, like changes to a user’s manager and group membership updates.

This capability may sound familiar- it’s already is available on our /v1.0 endpoint for drives and drive items, and we’ll be continuing to add support for more resources in the future.

For more details watch the video below or read on

Using delta query

Using delta query is simple- just add “/delta” on the end of a standard GET request. For example:

GET https://graph.microsoft.com/beta/users/delta

The typical end to end call pattern is as follows:

1. The application begins by calling a GET request with the delta function on the desired resource.
2. Microsoft Graph will send a response containing the requested resource and a state token, which is encoded in an opaque nextLink or deltaLink URL.
   1. If a nextLink URL is returned, there are additional pages of data to be retrieved in the session. The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
   2. If a deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the deltaLink URL to learn about changes to the resource.
3. When the application needs to learn about changes to the resource, it makes a new request using the deltaLink URL received in step 2. This request may be made immediately after completing step 2 or when the application checks for changes.

 Note: The application may decide to check for changes based on a set amount of time passing, or this may be triggered by an event like a webhook change notification being received or a User clicking a button in a UI.

4. Microsoft Graph returns a response describing changes to the resource since the previous request, and either a nextLink URL or a deltaLink URL.

You can find detailed examples containing series of requests and responses for various resources, along with additional information on using Delta Query in our documentation:  

• delta query Overview 
• Example: Events
• Example: Messages
• Example: Groups
• Example: Users
• Example: Drive

Scenarios

Applications with local data stores can use delta query to efficiently synchronize data with Microsoft Graph. Stateless apps without local data stores can also benefit from delta query by using it to perform simple change tracking on resources they are interested in.

Here’s are some examples of scenarios where delta query can be useful:

• A workflow service that notifies customers of specific events can use delta query on messages to detect and alert customers when they get mail from their boss marked as high priority.
• A security monitoring application can scan new emails for malicious content and track changes to the membership of sensitive security Groups, then alert an IT admin as soon as a risky event occurs.
• A ticket management system can use delta query to ensure that when a support agent leaves the company, their open cases are automatically sent back into the queue and keep the people picker used by dispatchers when assigning cases up to date.

Additional Details

Please take at our documentation , the video overview on Channel 9, and hear more about delta query (and other topics) on Episode 122 of the Office Developer Podcast.

Known limitations

Tracking changes to relationships on users and groups is only supported within the specific resource class for which changes are being tracked. For example, if a client is tracking changes on groups and has selected the members relationship, the client will only receive membership updates in the delta query response if those members are also groups. In other words, tracking group membership for users is not yet supported. The Microsoft Graph team understands that this is a high priority scenario and an update is targeted to be delivered soon.

//